@hank-warren/pi-auto-permissions 0.1.2 → 0.3.0

package/NOTICE.md

@@ -4,4 +4,4 @@ This package is a fork of [`@ogulcancelik/pi-auto-permissions`](https://github.c
 
 The original work is Copyright (c) 2026 Can Celik and is used under the MIT License included in [`LICENSE`](LICENSE).
 
-Fork-specific changes are Copyright (c) 2026 Hank Warren and are released under the same MIT License. They include the `reviewEvidence.userAnswerTools` dialog-answer evidence feature, proposed upstream in [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) / [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25), and the prompted-review evaluation log with explicit user feedback.
+Fork-specific changes are Copyright (c) 2026 Hank Warren and are released under the same MIT License. They include the `reviewEvidence.userAnswerTools` dialog-answer evidence feature, proposed upstream in [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) / [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25), the prompted-review evaluation log with explicit user feedback, and the single-line animated review status widget.

package/README.md

@@ -210,9 +210,38 @@ Each version 2 record contains the collected user request, exact command, compac
 
 Logging is disabled by default. Records can contain sensitive conversation text and shell commands, so keep the file private and out of repositories. Cancelled or interrupted prompts are not labeled or logged.
 
+## Reviewer usage sidecar
+
+Guardian reviews are model calls made outside the Pi agent loop, so they never appear in the session transcript and are invisible to tools that total usage from session files. Auto Permissions therefore appends one content-free record per completed review:
+
+```json
+{"v":1,"id":"3f2b…","ts":"2026-08-11T22:41:03.118Z","source":"auto-permissions","label":"guardian","provider":"anthropic","model":"claude-fable-5","usage":{"input":812,"output":96,"cacheRead":18442,"cacheWrite":0,"reasoning":48,"cost":0.0121}}
+```
+
+The record carries identity, timing, and counters only. It never contains prompts, commands, reviewer evidence, verdicts, or responses, which is what makes it safe to keep on by default:
+
+```json
+{
+  "usageLog": {
+    "enabled": true,
+    "path": "./usage.jsonl"
+  }
+}
+```
+
+The path defaults to `usage.jsonl` beside the Auto Permissions config and resolves relative to it. The file is created with mode `0600` and rotates to `usage.jsonl.1` once it passes 16 MB, keeping one previous generation. Writing is best effort: a failing sidecar never blocks or changes a permission decision.
+
+[`@hank-warren/pi-stats`](../pi-stats) reads `<agent dir>/<extension>/usage.jsonl` sidecars and shows this usage as its own `provider/model (guardian)` row. Set `"enabled": false` to stop recording.
+
 ## Review display
 
-The default UI shows guardian progress in a temporary widget below the editor. Configure it with:
+The default UI shows guardian progress as a single animated status line in a temporary widget below the editor:
+
+```text
+auto permissions · Git commit · ✶ waiting for openai-codex/gpt-5.6-luna
+```
+
+A sparkle spinner (`✶ ✸ ✻ ✽`) cycles while the guardian is reviewing and resolves to `✓ approved`, `↻ revision requested`, `? waiting for your approval`, or `✗ blocked`. The guardian's reason, when present, appears on a dim second line; the command itself is not repeated because it is already visible in the Bash tool box. Configure the widget with:
 
 ```json
 {

package/config.ts

@@ -27,6 +27,10 @@ export interface AutoPermissionsConfig {
     enabled: boolean;
     path: string;
   };
+  usageLog: {
+    enabled: boolean;
+    path: string;
+  };
   rules: Gate[];
   ui: {
     enabled: boolean;
@@ -147,6 +151,26 @@ function resolveEvaluationLog(
   };
 }
 
+function resolveUsageLog(
+  raw: Record<string, unknown>,
+  configFilePath: string,
+): AutoPermissionsConfig["usageLog"] {
+  const defaultPath = resolve(dirname(configFilePath), "usage.jsonl");
+  if (raw.usageLog === undefined) return { enabled: true, path: defaultPath };
+  if (!raw.usageLog || typeof raw.usageLog !== "object" || Array.isArray(raw.usageLog)) {
+    throw new Error("usageLog must be an object");
+  }
+  const usageLog = raw.usageLog as Record<string, unknown>;
+  if (usageLog.enabled !== undefined && typeof usageLog.enabled !== "boolean") {
+    throw new Error("usageLog.enabled must be boolean");
+  }
+  const enabled = usageLog.enabled !== false;
+  const configuredPath = optionalString(usageLog.path, "usageLog.path");
+  if (!configuredPath) return { enabled, path: defaultPath };
+  const expanded = configuredPath.startsWith("~/") ? join(homedir(), configuredPath.slice(2)) : configuredPath;
+  return { enabled, path: isAbsolute(expanded) ? expanded : resolve(dirname(configFilePath), expanded) };
+}
+
 function resolveUi(raw: Record<string, unknown>): AutoPermissionsConfig["ui"] {
   if (raw.ui === undefined) return { enabled: true, resultDisplayMs: 2500, placement: "widget" };
   if (!raw.ui || typeof raw.ui !== "object" || Array.isArray(raw.ui)) {
@@ -199,6 +223,7 @@ export function loadAutoPermissionsConfig(path = configPath()): AutoPermissionsC
     systemPrompt: resolvePrompt(raw, path),
     reviewEvidence: resolveReviewEvidence(raw),
     evaluationLog: resolveEvaluationLog(raw, path),
+    usageLog: resolveUsageLog(raw, path),
     rules: customRules,
     ui: resolveUi(raw),
   };

package/index.ts

@@ -16,6 +16,14 @@ import {
   type PromptEvaluationUserChoice,
 } from "./evaluation-log.js";
 import { findGates, type Gate } from "./gates.js";
+import { appendUsageRecord, buildUsageLogRecord } from "./usage-log.js";
+import {
+  reviewFrameIntervalMs,
+  reviewStatusFrame,
+  reviewStatusLines,
+  type ReviewDisplayState,
+  type ReviewLinePalette,
+} from "./widget-status.js";
 import {
   buildReviewEnvelope,
   collectReviewEvidence,
@@ -28,7 +36,6 @@ const WIDGET_KEY = "auto-permissions";
 const PROJECT_CONFIG_DIR_NAME = (PiCodingAgent as { CONFIG_DIR_NAME?: string }).CONFIG_DIR_NAME ?? ".pi";
 
 type BlockResult = { block: true; reason: string };
-type ReviewDisplayState = "waiting" | "approved" | "revise" | "ask_user" | "blocked";
 type ReviewTarget = { toolName: string; toolCallId?: string };
 type ReviewRow = {
   gate: Gate;
@@ -203,6 +210,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   let bashRendererRegistered = false;
   let bashRendererSourcePath: string | undefined;
   let clearWidgetTimer: ReturnType<typeof setTimeout> | undefined;
+  let widgetAnimTimer: ReturnType<typeof setInterval> | undefined;
   const reviewRows = new Map<string, ReviewRow>();
   const reviewRowInvalidators = new Map<string, () => void>();
   let reviewerLineage: ReviewerLineage | undefined;
@@ -357,6 +365,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       if (response.stopReason === "error") {
         throw new Error(response.errorMessage ?? "reviewer request failed");
       }
+      recordReviewerUsage(config, model, response.usage);
       const verdict = parsePermissionVerdict(assistantText(response.content));
       if (!sessionActive || signal?.aborted || reviewerGeneration !== attemptGeneration) {
         throw new Error("review timed out or was cancelled");
@@ -379,6 +388,19 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
   }
 
+  /**
+   * Reviewer calls never reach the session transcript, so their usage is invisible to
+   * tooling that reads session files. Record content-free counters in a sidecar instead.
+   */
+  function recordReviewerUsage(config: AutoPermissionsConfig, model: { provider: string; id: string }, usage: unknown): void {
+    if (!config.usageLog.enabled) return;
+    try {
+      appendUsageRecord(config.usageLog.path, buildUsageLogRecord(model.provider, model.id, usage));
+    } catch {
+      // Usage accounting is optional and must never block a permission decision.
+    }
+  }
+
   function untrustedMatches(command: string, config: AutoPermissionsConfig): Gate[] {
     return findGates(command, config.rules).filter((gate) => !trustedGroups.has(gate.group));
   }
@@ -458,6 +480,8 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   function clearReviewWidget(ctx: ExtensionContext): void {
     if (clearWidgetTimer) clearTimeout(clearWidgetTimer);
     clearWidgetTimer = undefined;
+    if (widgetAnimTimer) clearInterval(widgetAnimTimer);
+    widgetAnimTimer = undefined;
     if (ctx.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
   }
 
@@ -476,7 +500,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     ctx: ExtensionContext,
     config: AutoPermissionsConfig,
     gate: Gate,
-    command: string,
+    _command: string,
     target: ReviewTarget,
     state: ReviewDisplayState,
     detail?: string,
@@ -497,27 +521,45 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
 
     if (clearWidgetTimer) clearTimeout(clearWidgetTimer);
     clearWidgetTimer = undefined;
-    ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) => ({
-      render(width: number): string[] {
-        const status = state === "waiting"
-          ? theme.fg("warning", `◌ waiting for ${reviewer}`)
-          : state === "approved"
-            ? theme.fg("success", "✓ approved")
-            : state === "revise"
-              ? theme.fg("warning", "↻ revision requested")
-              : state === "ask_user"
-                ? theme.fg("accent", "? waiting for your approval")
-                : theme.fg("error", "✗ blocked");
-        const lines = [
-          `${theme.fg("accent", theme.bold("auto permissions"))} ${theme.fg("muted", `· ${gate.label}`)}`,
-          `  ${status}`,
-          theme.fg("dim", `  $ ${command}`),
-        ];
-        if (detail) lines.push(theme.fg("muted", `  ${detail}`));
-        return lines.map((line) => truncateToWidth(line, Math.max(1, width)));
-      },
-      invalidate() {},
-    }), { placement: "belowEditor" });
+    if (widgetAnimTimer) clearInterval(widgetAnimTimer);
+    widgetAnimTimer = undefined;
+    ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+      const palette: ReviewLinePalette = {
+        header: (text) => theme.fg("accent", theme.bold(text)),
+        muted: (text) => theme.fg("muted", text),
+        warning: (text) => theme.fg("warning", text),
+        success: (text) => theme.fg("success", text),
+        accent: (text) => theme.fg("accent", text),
+        error: (text) => theme.fg("error", text),
+      };
+      let frameIndex = 0;
+      let timer: ReturnType<typeof setInterval> | undefined;
+      const stopTimer = () => {
+        if (timer) clearInterval(timer);
+        if (widgetAnimTimer === timer) widgetAnimTimer = undefined;
+        timer = undefined;
+      };
+      const intervalMs = reviewFrameIntervalMs(state);
+      if (intervalMs !== undefined) {
+        timer = setInterval(() => {
+          frameIndex++;
+          if (reviewStatusFrame(state, reviewer, frameIndex).done) stopTimer();
+          tui.requestRender();
+        }, intervalMs);
+        timer.unref?.();
+        widgetAnimTimer = timer;
+      }
+      return {
+        render(width: number): string[] {
+          return reviewStatusLines(state, gate.label, reviewer, frameIndex, detail, palette)
+            .map((line) => truncateToWidth(line, Math.max(1, width)));
+        },
+        invalidate() {},
+        dispose() {
+          stopTimer();
+        },
+      };
+    }, { placement: "belowEditor" });
 
     if (autoClear) {
       clearWidgetTimer = setTimeout(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-auto-permissions",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Fork of @ogulcancelik/pi-auto-permissions with dialog-answer user evidence: context-aware Bash permissions for Pi with automated guardian review.",
   "type": "module",
   "keywords": [
@@ -43,6 +43,8 @@
     "evaluation-log.ts",
     "gates.ts",
     "review.ts",
+    "usage-log.ts",
+    "widget-status.ts",
     "README.md",
     "LICENSE"
   ],

package/usage-log.ts

@@ -0,0 +1,84 @@
+import { appendFileSync, chmodSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+
+/** Rotate once the sidecar grows past this size; one previous generation is kept. */
+export const USAGE_LOG_ROTATE_BYTES = 16 * 1024 * 1024;
+
+export interface UsageLogTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  reasoning: number;
+  cost: number;
+}
+
+/**
+ * One model call recorded outside the Pi session transcript. The record is deliberately
+ * content free: it carries identity, timing, and counters only, never prompts, commands,
+ * evidence, or responses.
+ */
+export interface UsageLogRecord {
+  v: 1;
+  id: string;
+  ts: string;
+  source: string;
+  label: string;
+  provider: string;
+  model: string;
+  usage: UsageLogTotals;
+}
+
+function count(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** Normalize a pi-ai usage payload, whose cost is an object with a total. */
+export function usageLogTotals(usage: unknown): UsageLogTotals {
+  const record = (usage && typeof usage === "object" ? usage : {}) as Record<string, unknown>;
+  const cost = (record.cost && typeof record.cost === "object" ? record.cost : {}) as Record<string, unknown>;
+  return {
+    input: count(record.input),
+    output: count(record.output),
+    cacheRead: count(record.cacheRead),
+    cacheWrite: count(record.cacheWrite),
+    reasoning: count(record.reasoning),
+    cost: count(typeof record.cost === "number" ? record.cost : cost.total),
+  };
+}
+
+export function buildUsageLogRecord(
+  provider: string,
+  model: string,
+  usage: unknown,
+  label = "guardian",
+  source = "auto-permissions",
+): UsageLogRecord {
+  return {
+    v: 1,
+    id: randomUUID(),
+    ts: new Date().toISOString(),
+    source,
+    label,
+    provider,
+    model,
+    usage: usageLogTotals(usage),
+  };
+}
+
+function rotateIfLarge(path: string): void {
+  try {
+    if (statSync(path).size < USAGE_LOG_ROTATE_BYTES) return;
+    renameSync(path, `${path}.1`);
+  } catch {
+    // A missing or unrotatable sidecar simply keeps appending.
+  }
+}
+
+export function appendUsageRecord(path: string, record: UsageLogRecord): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  rotateIfLarge(path);
+  appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+  chmodSync(path, 0o600);
+}

package/widget-status.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure helpers for the below-editor review status widget: single-line status
+ * formatting plus frame progression for the waiting sparkle spinner. Kept
+ * free of TUI dependencies so they are unit-testable.
+ */
+
+export type ReviewDisplayState = "waiting" | "approved" | "revise" | "ask_user" | "blocked";
+
+export type ReviewStatusTone = "warning" | "success" | "accent" | "error";
+
+export interface ReviewStatusFrame {
+  glyph: string;
+  label: string;
+  tone: ReviewStatusTone;
+  /** True once no further frames are needed (state is static). */
+  done: boolean;
+}
+
+export const WAITING_FRAMES = ["✶", "✸", "✻", "✽"] as const;
+export const WAITING_FRAME_INTERVAL_MS = 120;
+
+export function reviewStatusFrame(
+  state: ReviewDisplayState,
+  reviewer: string,
+  frameIndex: number,
+): ReviewStatusFrame {
+  const index = Math.max(0, Math.floor(frameIndex));
+  switch (state) {
+    case "waiting":
+      return {
+        glyph: WAITING_FRAMES[index % WAITING_FRAMES.length],
+        label: `waiting for ${reviewer}`,
+        tone: "warning",
+        done: false,
+      };
+    case "approved":
+      return { glyph: "✓", label: "approved", tone: "success", done: true };
+    case "revise":
+      return { glyph: "↻", label: "revision requested", tone: "warning", done: true };
+    case "ask_user":
+      return { glyph: "?", label: "waiting for your approval", tone: "accent", done: true };
+    case "blocked":
+      return { glyph: "✗", label: "blocked", tone: "error", done: true };
+  }
+}
+
+export function reviewFrameIntervalMs(state: ReviewDisplayState): number | undefined {
+  return state === "waiting" ? WAITING_FRAME_INTERVAL_MS : undefined;
+}
+
+export interface ReviewLinePalette {
+  header: (text: string) => string;
+  muted: (text: string) => string;
+  warning: (text: string) => string;
+  success: (text: string) => string;
+  accent: (text: string) => string;
+  error: (text: string) => string;
+}
+
+export const PLAIN_PALETTE: ReviewLinePalette = {
+  header: (text) => text,
+  muted: (text) => text,
+  warning: (text) => text,
+  success: (text) => text,
+  accent: (text) => text,
+  error: (text) => text,
+};
+
+/**
+ * Render the widget content: one status line, plus a dim detail line only
+ * when a guardian reason is present. The command is intentionally omitted —
+ * it is already visible in the bash tool box above.
+ */
+export function reviewStatusLines(
+  state: ReviewDisplayState,
+  gateLabel: string,
+  reviewer: string,
+  frameIndex: number,
+  detail: string | undefined,
+  palette: ReviewLinePalette,
+): string[] {
+  const frame = reviewStatusFrame(state, reviewer, frameIndex);
+  const status = palette[frame.tone](`${frame.glyph} ${frame.label}`);
+  const lines = [
+    `${palette.header("auto permissions")} ${palette.muted(`· ${gateLabel} ·`)} ${status}`,
+  ];
+  if (detail) lines.push(palette.muted(`  ${detail}`));
+  return lines;
+}