bermudis-pi-goodies 0.13.2 → 0.13.4

package/README.md

@@ -23,7 +23,7 @@ extensions. One entry point, eleven independent features.
 After publishing the package to npm:
 
 ```bash
-pi install npm:bermudis-pi-goodies@0.13.2
+pi install npm:bermudis-pi-goodies@0.13.4
 ```
 
 Remove any old `bermudis-pi-goodies.ts` symlink before reloading Pi. Each
@@ -53,6 +53,11 @@ are no extra endpoints or keys to configure. `/goodies list` shows whether
 summaries are on or off, and `/goodies summary-model off` disables them
 again.
 
+Failures are invisible in the TUI (pi owns the terminal), so each distinct
+failure is also appended to `~/.pi/agent/goodies.log` (capped at 256 KB,
+oldest lines dropped), along with one `clean-tui active; summary-model=…`
+line per load. If summaries silently stop, look there first.
+
 Two practical notes:
 
 - **Pick a fast non-thinking model.** Summaries get a tiny response budget;
@@ -93,12 +98,19 @@ clean-tui therefore follows two rules in its render paths:
 - **Height-neutral swaps:** text that may be replaced by a summary later is
   capped at the same width as summaries (`BASH_BULLET_WIDTH`), so an
   arriving summary never collapses a wrapped line (rule 1).
-- **Pending-only refresh:** when a summary lands, only rows whose tool is
-  still executing are re-rendered — those sit at the transcript tail, inside
-  the viewport, so the swap is a cheap differential update. Finished rows
+- **Tail-only refresh:** when a summary lands, only rows that are still
+  executing, or that finished while their summary was in flight (bounded by
+  a ~10s freshness window), are re-rendered — at landing such rows sit at
+  the transcript tail, inside the viewport, so the swap is a cheap
+  differential update. This is what lets fast commands — finished before
+  the ~2s summary arrives — show their summary at all. Older finished rows
   (including replayed ones from before a `/resume`) keep the raw command
   text for the rest of the session; the summary stays cached, and future
   rows of the same command render it from the start (rule 2).
+- **Queued, not dropped:** burst rows beyond the two-concurrent-requests
+  cap, and requests deferred by failure backoff, are queued and drained
+  when a slot frees — never silently dropped (their rows may never
+  re-render to retry).
 
 To catch a flash red-handed, run `PI_DEBUG_REDRAW=1 pi`, reproduce, then
 `grep fullRender ~/.pi/agent/pi-debug.log` — every line is one screen wipe

package/clean-tui.ts

@@ -35,6 +35,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Text } from "@earendil-works/pi-tui";
 import { homedir } from "node:os";
+import { join } from "node:path";
+import { appendFileSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import {
   findSummaryModel,
@@ -132,6 +134,14 @@ type Entry = {
   hasImage?: boolean;
   /** Content array of the last result seen; detects real mutations vs re-renders. */
   contentRef?: unknown;
+  /**
+   * When a summary request was first fired for this entry's command. A row
+   * whose result landed after this stamp finished while its summary was in
+   * flight — it may still swap when the summary lands (viewport-tail safe).
+   */
+  summaryRequestedAt?: number;
+  /** When the first genuine tool result landed (stamped in recordResult). */
+  resultAt?: number;
 };
 
 let liveSeg = 0;
@@ -270,6 +280,7 @@ function recordResult(entry: Entry | undefined, result: any, ctx: any) {
   if (!entry || entry.contentRef === result?.content) return;
   entry.contentRef = result?.content;
   entry.result = result;
+  entry.resultAt = Date.now();
   entry.isError = !!ctx.isError || !!result.isError;
   entry.hasImage = hasImageContent(result);
   revalidateBurstsAround(entry.toolCallId);
@@ -312,6 +323,10 @@ const SUMMARY_ERROR_SNIPPET_CHARS = 200;
 
 const summaryCache = new Map<string, string>();
 const pendingSummaries = new Set<string>();
+// Commands whose requests were deferred by the inflight cap or a failure
+// backoff. Drained whenever a slot frees (request settle) or a later
+// renderCall finds capacity — no timers. Cleared on session switch.
+const summaryRequestQueue: string[] = [];
 // A burst of distinct long commands can fan out N simultaneous renders; keep
 // concurrent provider requests bounded so we don't hammer the rate limiter.
 const SUMMARY_MAX_INFLIGHT = 2;
@@ -323,6 +338,7 @@ export function __setSummaryEnabled(v: boolean): void {
 export function __clearSummaryCache(): void {
   summaryCache.clear();
   pendingSummaries.clear();
+  summaryRequestQueue.length = 0;
   summaryFailuresLogged.clear();
   summaryFailStreak = 0;
   summaryBlockedUntil = 0;
@@ -449,10 +465,48 @@ function logSummaryFailure(cmd: string, err: unknown, pauseMs?: number) {
   const key = `${msg}${pause}`;
   if (summaryFailuresLogged.has(key)) return;
   summaryFailuresLogged.add(key);
-  console.error(
-    `[clean-tui] command summary failed (${msg})${pause}; keeping heuristic hint. ` +
-      `Command starts: ${JSON.stringify(cmd.slice(0, 60))}`,
-  );
+  const detail =
+    `command summary failed (${msg})${pause}; keeping heuristic hint. ` +
+    `Command starts: ${JSON.stringify(cmd.slice(0, 60))}`;
+  console.error(`[clean-tui] ${detail}`);
+  appendSummaryLog(detail);
+}
+
+// ── Summary log file ────────────────────────────────────────────
+//
+// console.error is invisible in TUI mode (pi owns the terminal), so summary
+// failures also append to a small capped log file next to goodies.json and
+// pi-debug.log. Failures only — successes are noise. Every fs call is
+// guarded: an unwritable log destination must never break rendering or
+// swallow the original error (console.error above already carried it).
+const SUMMARY_LOG_DEFAULT_PATH = join(homedir(), ".pi", "agent", "goodies.log");
+let summaryLogPath = SUMMARY_LOG_DEFAULT_PATH;
+const SUMMARY_LOG_MAX_BYTES = 256 * 1024;
+const SUMMARY_LOG_KEEP_BYTES = 64 * 1024;
+
+/** Redirect the failure log (tests point this at scratch storage). */
+export function __setSummaryLogPathForTesting(path?: string): void {
+  summaryLogPath = path ?? SUMMARY_LOG_DEFAULT_PATH;
+}
+
+function appendSummaryLog(line: string): void {
+  const stamped = `${new Date().toISOString()} [${process.pid}] ${line}`;
+  try {
+    if (statSync(summaryLogPath).size > SUMMARY_LOG_MAX_BYTES) {
+      // Size cap without timers or rotation daemons: keep the newest tail.
+      writeFileSync(
+        summaryLogPath,
+        readFileSync(summaryLogPath).subarray(-SUMMARY_LOG_KEEP_BYTES),
+      );
+    }
+  } catch {
+    // Missing/unreadable file — the append below (re)creates it.
+  }
+  try {
+    appendFileSync(summaryLogPath, `${stamped}\n`);
+  } catch {
+    // Unwritable destination — nothing else to do; console.error carried it.
+  }
 }
 
 // Failure backoff: requestSummary runs on every bash renderCall, so after a
@@ -494,6 +548,9 @@ function noteSummaryFailure(err: unknown): number {
 }
 
 function requestSummary(cmd: string): void {
+  // Deferred requests drain here too: renderCalls are the heartbeat that
+  // notices backoff expiry when nothing else is in flight.
+  drainSummaryQueue();
   // Guard order matters: renderCall fires on every rerender, so all guards
   // here are cheap sync checks, and anything that can differ across rerenders
   // of the same command must not mutate state (mutating in a render path once
@@ -503,12 +560,29 @@ function requestSummary(cmd: string): void {
     replaying ||
     !isSummarizable(cmd) ||
     !getSummaryModel() || // unset = feature off: no resolution, no network.
-    summaryCache.has(cmd) ||
-    pendingSummaries.has(cmd) ||
+    summaryCache.has(cmd)
+  )
+    return;
+  // Stamp before any deferral: a row whose result lands while its summary is
+  // queued or in flight may still swap when the summary arrives (see
+  // invalidateRowsForCommand) — at landing such rows are at most one summary
+  // latency old, so they sit at the viewport tail.
+  stampSummaryRequested(cmd);
+  if (pendingSummaries.has(cmd) || summaryRequestQueue.includes(cmd)) return;
+  if (
     Date.now() < summaryBlockedUntil ||
     pendingSummaries.size >= SUMMARY_MAX_INFLIGHT
-  )
+  ) {
+    // Defer, don't drop: a burst of N commands renders faster than summaries
+    // complete, and a dropped request would never retry (its row may not
+    // re-render). Drained on settle and on later renderCalls.
+    summaryRequestQueue.push(cmd);
     return;
+  }
+  startSummaryRequest(cmd);
+}
+
+function startSummaryRequest(cmd: string): void {
   pendingSummaries.add(cmd);
   const signal = summarySessionAbort.signal;
   activeBackend()
@@ -533,29 +607,72 @@ function requestSummary(cmd: string): void {
       if (signal.aborted || (err as Error)?.name === "AbortError") return;
       const pauseMs = noteSummaryFailure(err);
       logSummaryFailure(cmd, err, pauseMs);
+    })
+    .finally(() => {
+      if (!signal.aborted) drainSummaryQueue();
     });
 }
 
+/** Start queued requests while capacity allows and no backoff is active. */
+function drainSummaryQueue(): void {
+  while (
+    summaryRequestQueue.length > 0 &&
+    pendingSummaries.size < SUMMARY_MAX_INFLIGHT &&
+    Date.now() >= summaryBlockedUntil
+  ) {
+    const cmd = summaryRequestQueue.shift()!;
+    if (summaryCache.has(cmd) || pendingSummaries.has(cmd)) continue;
+    startSummaryRequest(cmd);
+  }
+}
+
+function stampSummaryRequested(cmd: string): void {
+  const now = Date.now();
+  for (const e of entries) {
+    if (e.args?.command === cmd && e.summaryRequestedAt === undefined)
+      e.summaryRequestedAt = now;
+  }
+}
+
 function invalidateRowsForCommand(cmd: string): void {
-  // Only rows that are STILL EXECUTING get refreshed when a summary lands.
-  // Executing rows sit at the transcript tail, inside pi's viewport, so the
-  // re-render is a cheap differential line update. Finished rows — including
-  // replayed ones from before a /resume — can sit far above the viewport on a
-  // long transcript, and pi's diff renderer answers any change above the
-  // viewport with fullRender(true): clear screen + scrollback wipe + full
-  // repaint, i.e. the "flicker while pi is working" seen on 0.11.x (fits any
-  // width; reproduced reasoning from tui-main-screen.js `firstChanged <
-  // prevViewportTop`). Finished rows simply keep the raw command text, which
-  // is more informative than the summary anyway; the summary stays cached
-  // and future rows of the same command render it from the start.
+  // Refresh rows that are STILL EXECUTING, plus rows that finished while
+  // their summary was in flight — at landing those are at most one summary
+  // latency old, so they sit at the viewport tail and a differential
+  // re-render is safe. This is what makes fast commands (finished before the
+  // ~2s summary arrives) visibly summarize at all. Older finished rows —
+  // including replayed ones from before a /resume — keep the raw command
+  // text: they can sit far above the viewport on a long transcript, and pi's
+  // diff renderer answers any change above the viewport with fullRender(true):
+  // clear screen + scrollback wipe + full repaint, i.e. the "flicker while pi
+  // is working" seen on 0.11.x. The summary stays cached either way, and
+  // future rows of the same command render it from the start.
   for (const e of entries) {
-    if (!e.result && e.args?.command === cmd) {
+    if (e.args?.command !== cmd) continue;
+    const finishedDuringFlight =
+      e.resultAt !== undefined &&
+      e.summaryRequestedAt !== undefined &&
+      e.resultAt >= e.summaryRequestedAt &&
+      // Strictly younger than the window: a zero window must admit nothing,
+      // and stamp/result often land in the same millisecond in tests.
+      Date.now() - e.resultAt < summarySwapMaxAgeMs;
+    if (!e.result || finishedDuringFlight) {
       const fn = invalidateById.get(e.toolCallId);
       if (fn) fn();
     }
   }
 }
 
+// Bounds how long after finishing a row may still swap. Covers the normal
+// race (summary lands ~2s after start, row finished ≤2s ago) with margin;
+// backoff-delayed landings (30s+) exceed it and correctly keep raw text,
+// since such rows may have scrolled above the viewport.
+const SUMMARY_SWAP_MAX_AGE_MS = 10_000;
+let summarySwapMaxAgeMs = SUMMARY_SWAP_MAX_AGE_MS;
+
+export function __setSummarySwapMaxAgeForTesting(ms: number): void {
+  summarySwapMaxAgeMs = ms;
+}
+
 function bgFor(
   pending: boolean,
   isError: boolean,
@@ -698,6 +815,11 @@ function formatLsBullet(entry: Entry, theme: any): string {
 
 export default function cleanTui(pi: ExtensionAPI): void {
   setCleanTuiActive(true);
+  // One line per load (pi process start, /reload) so the log answers "was the
+  // feature even on, and pointing at which model" without guessing.
+  appendSummaryLog(
+    `clean-tui active; summary-model=${getSummaryModel() ?? "off"}`,
+  );
   const schemaTools = getBuiltInTools(process.cwd());
 
   pi.on("agent_start", (_event, ctx) => {
@@ -749,6 +871,7 @@ export default function cleanTui(pi: ExtensionAPI): void {
     entryById.clear();
     invalidateById.clear();
     pendingSummaries.clear();
+    summaryRequestQueue.length = 0;
     // Capture the registry slice render context lacks, and cut off any
     // summaries still in flight from the previous session.
     const modelRegistry = (
@@ -889,8 +1012,9 @@ export default function cleanTui(pi: ExtensionAPI): void {
       );
     },
     renderCall(args, theme, ctx: any) {
-      if (args.command) requestSummary(args.command);
+      // Upsert before requestSummary so the stamp sees this row's entry.
       const entry = upsertEntry(ctx.toolCallId, "bash", args, ctx.invalidate);
+      if (args.command) requestSummary(args.command);
       const burst = getBurstForId(ctx.toolCallId);
       const isGrouped = burst && burst.entries.length > 1;
       const isLeader =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bermudis-pi-goodies",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bermudi/agent-extensions.git",