pi-zip 0.2.4 → 0.2.6

package/README.md

@@ -34,14 +34,25 @@ Known limits:
 
 ## What you see
 
-At most one line per turn, only when something was folded:
+At most one line per turn in the transcript, only when the context was folded or summarized. The numbers come first, and the bar shows how much is left:
 
 ```
-pi-zip · folded 12 old outputs · 84.2K → 31.5K tokens · 0.9 ms · originals recallable
-pi-zip · summarized 64 requests · 182K → 41K tokens · 8.4 s (done while you were away)
+▸ pi-zip  74K → 43K  ▰▰▰▰▰▰▱▱▱▱  folded 12 old outputs
+          originals are kept; the model can recall any of them with zip_recall
+▸ pi-zip  182K → 41K  ▰▰▱▱▱▱▱▱▱▱  summarized 64 requests · ready while you were away
 ```
 
-The line goes to the UI only; it never enters the model's context. Nothing else is added to the screen.
+The second line appears once per session. Expand tool output (ctrl+o) to see why it happened now and what was folded:
+
+```
+▸ pi-zip  74K → 43K  ▰▰▰▰▰▰▱▱▱▱  folded 12 old outputs
+          cache cold (away 47 min): this request rewrites it anyway, so editing is free
+          bash npm test        turn 1     14K  k3x9q2m7ab
+          read src/payment.ts  turn 1      9K  p8d2x1qa0m
+          … 10 more
+```
+
+These lines are saved in the session, so they are still there after a restart, but they are never sent to the model. On narrow terminals the words go first, then the bar; the numbers always stay. A summary still shows up as Pi's own `[compaction]` block as well; the pi-zip line next to it tells you who made it. Recalls show up as ordinary `zip_recall` tool calls.
 
 ## The three rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-zip",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Keeps long Pi sessions cheap without losing anything: folds old tool output only when the prompt cache has already gone cold, and every fold can be recalled byte for byte. Zero config.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -1,15 +1,42 @@
 // pi-zip: keeps long Pi sessions cheap without losing anything. Wiring only; the logic lives in the sibling modules.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerZipCommand } from "./notice.ts";
+import type { Any } from "./util.ts";
+import { type NoticeData, registerZipCommand, renderNotice } from "./notice.ts";
 import { RECALL_TOOL } from "./placeholder.ts";
 import { registerRecallTool } from "./recall.ts";
-import { Zip } from "./run.ts";
+import { NOTICE_CUSTOM, Zip } from "./run.ts";
 
 export default function piZip(pi: ExtensionAPI) {
 	if (process.env.PI_ZIP_OFF === "1") return; // test only: behave exactly as if not installed (registers nothing)
 	const zip = new Zip(pi);
 	registerRecallTool(pi, zip); // stays registered even when off: earlier folds must stay recallable, and a tool-list change would bust the cache
 	registerZipCommand(pi, zip);
+	try {
+		// fold/summary notices stay in the transcript as one dim line (a custom entry: never part of the model's context)
+		let vw: (s: string) => number = (s) => s.length;
+		import("@earendil-works/pi-tui").then((m: Any) => {
+			if (typeof m?.visibleWidth === "function") vw = m.visibleWidth;
+		}, () => {});
+		pi.registerEntryRenderer?.(NOTICE_CUSTOM, (entry: Any, o: Any, theme: Any) => {
+			const d = entry?.data;
+			if (!d?.text) return undefined;
+			const data: NoticeData = d.v === 2 ? d : { v: 2, text: d.text, before: 0, after: 0, desc: "" };
+			return {
+				render: (width: number) => {
+					if (d.v !== 2) return [theme.fg("dim", vw(d.text) > width ? d.text.slice(0, Math.max(0, width - 1)) + "…" : d.text)];
+					try {
+						return renderNotice(data, !!o?.expanded, width, theme, vw);
+					} catch {
+						return [];
+					}
+				},
+				invalidate: () => {},
+			};
+		});
+		zip.entryRenderer = typeof pi.registerEntryRenderer === "function";
+	} catch {
+		/* older Pi: notices fall back to the status line */
+	}
 	// A tool allowlist (`pi --tools read,bash`, sub-agent launchers) replaces the whole selection and Pi then does not even register
 	// zip_recall; folds of outputs the model could not get back would be lost, so only rereadable outputs fold then (plan rereadOnly).
 	const checkRecall = () => {

package/src/notice.ts

@@ -12,19 +12,90 @@ export interface NoticeAction {
 	pressure?: boolean; // done by the warm valve (the law fired while the cache is still warm), not because the cache was cold
 }
 
+/** One folded output, for the expanded (ctrl+o) view of a notice. */
+export interface NoticeItem {
+	label: string; // tool + short args
+	turn?: number;
+	tokens: number;
+	handle: string;
+}
+
+/** What a transcript notice stores (custom entry data; never sent to the model). `text` is the plain one-line form (status-line fallback, ledger). */
+export interface NoticeData {
+	v: 2;
+	text: string;
+	before: number;
+	after: number;
+	desc: string; // "folded 12 old outputs · summarized 64 requests · ready while you were away"
+	why?: string; // expanded view: why now
+	items?: NoticeItem[];
+	more?: number; // folded outputs not listed
+	first?: boolean; // the session's first notice: say once that originals are kept
+}
+
 export const fmtK = (tokens: number): string => `${tokens >= 99_500 ? Math.round(tokens / 1000) : Math.round(tokens / 100) / 10}K`;
 
+const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? "" : "s"}`;
+const secs = (ms: number) => `${(Math.round(ms / 100) / 10).toFixed(1)} s`;
+
+/** The words after the numbers: what happened, plus how long the user waited for a summary (if at all). */
+export function noticeDesc(actions: NoticeAction[]): string {
+	return actions
+		.map((a) => {
+			if (a.kind === "fold") return `folded ${plural(a.count, "old output")}`;
+			return `summarized ${plural(a.count, "request")} · ${a.prepared ? "ready while you were away" : `waited ${secs(a.ms)}`}`;
+		})
+		.join(" · ");
+}
+
 export function noticeText(actions: NoticeAction[]): string {
-	const segs = actions.map((a) => {
-		const sizes = `${fmtK(a.tokensBefore)} → ${fmtK(a.tokensAfter)} tokens`;
-		if (a.kind === "fold") {
-			const ms = a.ms < 10 ? (Math.round(a.ms * 10) / 10).toFixed(1) : String(Math.round(a.ms));
-			return `folded ${a.count} old output${a.count === 1 ? "" : "s"} · ${sizes} · ${ms} ms · originals recallable${a.pressure ? " · context over the warm-cache limit" : ""}`;
-		}
-		const s = (Math.round(a.ms / 100) / 10).toFixed(1);
-		return `summarized ${a.count} request${a.count === 1 ? "" : "s"} · ${sizes} · ${a.prepared ? `${s} s (done while you were away)` : `waited ${s} s`}`;
-	});
-	return `${PRODUCT} · ${segs.join(" · ")}`;
+	const first = actions[0], last = actions[actions.length - 1];
+	return `${PRODUCT}  ${fmtK(first.tokensBefore)} → ${fmtK(last.tokensAfter)}  ${noticeDesc(actions)}`;
+}
+
+/** Ten cells, filled in proportion to what is left: length is read before any digit is. */
+export function ratioBar(before: number, after: number, cells = 10): string {
+	const f = before > 0 ? Math.min(cells, Math.max(1, Math.round((cells * after) / before))) : cells;
+	return "▰".repeat(f) + "▱".repeat(cells - f);
+}
+
+export interface NoticeTheme {
+	fg(color: string, text: string): string;
+}
+
+const MARK = "▸ ";
+const INDENT = " ".repeat(MARK.length + PRODUCT.length + 2);
+
+/** Lines for the transcript. Narrow terminals drop whole segments in order (description, then bar); the numbers always stay.
+ *  `w` measures display width (Pi's visibleWidth in the renderer; string length in tests). Every line fits `width`. */
+export function renderNotice(d: NoticeData, expanded: boolean, width: number, th: NoticeTheme, w: (s: string) => number = (s) => s.length): string[] {
+	const nums = `${fmtK(d.before)} → ${fmtK(d.after)}`;
+	const bar = ratioBar(d.before, d.after);
+	const tries: [string, string][] = [
+		[`${MARK}${PRODUCT}  ${nums}  ${bar}  ${d.desc}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}  ${th.fg("dim", bar)}  ${th.fg("dim", d.desc)}`],
+		[`${MARK}${PRODUCT}  ${nums}  ${bar}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}  ${th.fg("dim", bar)}`],
+		[`${MARK}${PRODUCT}  ${nums}`, `${th.fg("accent", MARK + PRODUCT)}  ${th.fg("text", nums)}`],
+		[nums, th.fg("text", nums)],
+	];
+	const head = tries.find(([plain]) => w(plain) <= width);
+	if (!head) return [];
+	const out = [head[1]];
+	const sub = (plain: string) => {
+		const line = INDENT + plain;
+		if (w(line) <= width) out.push(th.fg("dim", line));
+		else if (w(plain) <= width) out.push(th.fg("dim", plain));
+	};
+	if (d.first) sub("originals are kept; the model can recall any of them with zip_recall");
+	if (!expanded) return out;
+	if (d.why) sub(d.why);
+	const items = d.items ?? [];
+	const lw = Math.min(28, Math.max(0, ...items.map((i) => i.label.length)));
+	for (const i of items) {
+		const label = i.label.length > lw ? i.label.slice(0, lw - 1) + "…" : i.label.padEnd(lw);
+		sub(`${label}  ${(i.turn ? `turn ${i.turn}` : "").padEnd(8)}${fmtK(i.tokens).padStart(6)}  ${i.handle}`);
+	}
+	if (d.more) sub(`… ${d.more} more`);
+	return out;
 }
 
 export class Stats {

package/src/run.ts

@@ -6,7 +6,7 @@ import { dirname } from "node:path";
 import { detectCold, lastMessageMs, lastPrompt, modelKey, resolveTtl, ttlFor } from "./cache.ts";
 import { describe, lawPrices, loadStats, pWarm, record, sample, GAP_EDGES, type Entry } from "./learn.ts";
 import { validateEdits, repairPayload } from "./guard.ts";
-import { fmtK, Stats, noticeText, type NoticeAction, type ZipControl } from "./notice.ts";
+import { fmtK, Stats, noticeDesc, noticeText, type NoticeAction, type NoticeData, type ZipControl } from "./notice.ts";
 import { applyPlanToMessages, buildBlocks, calibrate, countUserTurns, G0, planContext, reserveTokensFor, untouchedEst, type Block, type Calibration, type Cut, type FoldTarget, type Law, type PlanOpts, type PlanResult, type RunPlan } from "./plan.ts";
 import { handleFor, PH_MARK, RECALL_TOOL } from "./placeholder.ts";
 import { recalledHandlesFromBranch } from "./recall.ts";
@@ -16,6 +16,8 @@ import { type Any, PRODUCT, textOf, tok4 } from "./util.ts";
 export const PLAN_CUSTOM = "pi-zip/plan";
 export const STATE_CUSTOM = "pi-zip/state";
 export const STEER_CUSTOM = "pi-zip/steer";
+const fmtAway = (s: number) => (s < 90 ? `${Math.round(s)} s` : s < 5400 ? `${Math.round(s / 60)} min` : `${(Math.round(s / 360) / 10).toFixed(1)} h`);
+export const NOTICE_CUSTOM = "pi-zip/notice"; // a fold/summary notice kept in the transcript (rendered by index.ts, never sent to the model)
 export const UNUSED_SUMMARY_CUSTOM = "pi-zip/unused-summary"; // a background summary nobody adopted: its cost, so the session totals stay honest
 export const AWAY_FRACTION = 0.8; // the away-timer fires this far into the cache lifetime
 // Other context managers rewrite the view too (F14); two writers give unpredictable results, so we pause and keep only the Guard.
@@ -95,6 +97,10 @@ export class Zip implements ZipControl {
 
 	/** zip_recall declared to the model? Checked at session start and before every run (index.ts); a `--tools` allowlist hides it. */
 	recallOk = true;
+	/** index.ts registered the transcript renderer for NOTICE_CUSTOM (Pi versions without registerEntryRenderer fall back to a status line). */
+	entryRenderer = false;
+	private coldWhy = ""; // the expanded notice's "why now" for this run
+	private noticed = false; // a transcript notice was written in this process (the branch may not show it yet)
 	/** A summary was persisted since the last cold run start: later warm plans make none unless at the compaction room. */
 	summarizedWarm = false;
 	setRecallOk(ok: boolean) {
@@ -111,9 +117,19 @@ export class Zip implements ZipControl {
 		} catch {}
 	}
 
-	private notify(ctx: Any, text: string) {
+	/** keep = a fold/summary notice: written to the session as a custom entry, so it stays in the transcript (also after a restart)
+	 *  next to Pi's own "[compaction]" block instead of a status line the next status overwrites. Custom entries never reach the model. */
+	private notify(ctx: Any, text: string, keep?: NoticeData) {
 		this.stats.notices++;
 		this.ledger({ type: "notice", text });
+		if (keep && ctx?.mode === "tui" && this.entryRenderer) {
+			setTimeout(() => { // after Pi has appended this turn's edits
+				try {
+					this.pi.appendEntry(NOTICE_CUSTOM, keep);
+				} catch {}
+			}, 0);
+			return;
+		}
 		if (ctx?.ui?.notify && (ctx.mode === "tui" || ctx.mode === "rpc")) {
 			try {
 				ctx.ui.notify(text, "info");
@@ -243,6 +259,7 @@ export class Zip implements ZipControl {
 		this.survSrc = src;
 		this.runChecked = false; // the first request decides (cold: the cold plan; warm: only above the cap, if the law fires)
 		this.coldReason = reason;
+		this.coldWhy = src === "model switch" ? "model switched: its cache starts empty, so this request rewrites it anyway" : cold && gapS !== null ? `cache cold (away ${fmtAway(gapS)}): this request rewrites it anyway, so editing is free` : "";
 		for (const h of recalledHandlesFromBranch(branch)) this.recalled.add(h);
 		for (let i = branch.length - 1; i >= 0; i--) {
 			const en = branch[i];
@@ -565,7 +582,14 @@ export class Zip implements ZipControl {
 			const prepared = plan.source === "settle" && waitMs < 500; // finished while the user was away: report the real production time, not the zero wait
 			notices.push({ kind: "summary", count: cut.count, tokensBefore: ctxTokens - (before - after), tokensAfter: ctxTokens - (before - after) - cutSaved, ms: prepared ? cut.ms : waitMs, prepared, pressure: valve });
 		}
-		if (notices.length && !this.quiet) this.notify(ctx, noticeText(notices));
+		if (notices.length && !this.quiet) {
+			const ITEMS = 8;
+			const items = live.slice(0, ITEMS).map((t) => ({ label: `${t.tool}${t.args ? " " + t.args : ""}`, turn: byId.get(t.entryId)?.userTurn, tokens: Math.round(k * t.entryTokens), handle: handleFor(t.entryId) }));
+			const why = valve ? "cache still warm, but the context passed the warm-cache limit" : this.cold ? this.coldWhy : "cache warm: the reads saved pay for the rewrite";
+			const data: NoticeData = { v: 2, text: noticeText(notices), before: Math.round(notices[0].tokensBefore), after: Math.round(notices[notices.length - 1].tokensAfter), desc: noticeDesc(notices), why: why || undefined, items, more: Math.max(0, live.length - ITEMS) || undefined, first: !this.noticed && !this.branch(ctx).some((en: Any) => en?.type === "custom" && en.customType === NOTICE_CUSTOM) };
+			this.noticed = true;
+			this.notify(ctx, data.text, data);
+		}
 		return { entries: [...e.entries, ...ours] }; // append, never overwrite other extensions' drafts
 	}