pi-zip 0.2.7 → 0.3.0-rc.1

package/src/notice.ts

@@ -1,7 +1,7 @@
 // User-facing text (F15, F16): one notice line per turn, honest stats, the /zip command. Notices never enter model context.
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type Any, PRODUCT } from "./util.ts";
-import type { CardData, StateWord } from "./ui.ts";
+import { brand, type CardData, type StateWord, SYM } from "./ui.ts";
 
 export interface NoticeAction {
 	kind: "fold" | "summary";
@@ -9,6 +9,7 @@ export interface NoticeAction {
 	tokensBefore: number;
 	tokensAfter: number;
 	ms: number;
+	waitMs?: number; // summary: how long the user waited for it (ms = how long it took to write)
 	prepared?: boolean; // summary computed while the user was away
 	pressure?: boolean; // done by the warm valve (the law fired while the cache is still warm), not because the cache was cold
 }
@@ -26,80 +27,126 @@ export interface NoticeData {
 	v: 2;
 	kind?: "state" | "card"; // absent: a fold/summary notice
 	word?: StateWord;
+	key?: string; // a state line shown once per session under this key (default: its word)
 	reason?: string;
 	card?: CardData;
 	text: string;
 	before: number;
 	after: number;
-	desc: string; // "folded 12 old outputs · summarized 64 requests · ready while you were away"
+	desc: string; // "zipped 12 old outputs in 6 ms · summarized 64 requests in 38.2 s · ready while you were away" (older entries: "folded …")
 	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
+	reqTs?: number; // when the first request carrying this plan went out (ms): the renderer shows that request's real size as "after"
 }
 
 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`;
+const dur = (ms: number) => (ms < 950 ? `${Math.max(1, Math.round(ms))} ms` : secs(ms));
 
 /** 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)}`}`;
+			if (a.kind === "fold") return `zipped ${plural(a.count, "old output")} in ${dur(a.ms)}`;
+			const wait = a.prepared ? 0 : (a.waitMs ?? a.ms);
+			const took = `summarized ${plural(a.count, "request")}`;
+			if (a.prepared) return `${took} in ${dur(a.ms)} · ready while you were away`;
+			if (wait >= a.ms - 500) return `${took} · waited ${secs(wait)}`; // the user waited for all of it
+			return `${took} in ${dur(a.ms)} · waited ${secs(wait)}`; // started while away, finished after the return
 		})
 		.join(" · ");
 }
 
-export function noticeText(actions: NoticeAction[]): string {
-	const first = actions[0], last = actions[actions.length - 1];
-	return `${PRODUCT}  ${fmtK(first.tokensBefore)} → ${fmtK(last.tokensAfter)}  ${noticeDesc(actions)}`;
+/** The description split for the line: what happened (verbs) and how long it took / waited (tail). Reads old entries too. */
+export function splitDesc(desc: string): { verbs: string[]; tail: string[] } {
+	const verbs: string[] = [], tail: string[] = [];
+	for (const part of desc.split(" · ").filter(Boolean)) {
+		const m = /^(?:folded|zipped|summarized) (.*?)(?: in ([\d.]+ m?s))?$/.exec(part);
+		if (m) {
+			verbs.push(part.replace(/^folded /, "zipped ").replace(/ in [\d.]+ m?s$/, ""));
+			if (m[2]) tail.push(m[2]);
+		} else tail.push(part);
+	}
+	return { verbs, tail };
 }
 
-/** 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 function noticeText(actions: NoticeAction[]): string {
+	const first = actions[0], last = actions[actions.length - 1];
+	const { verbs, tail } = splitDesc(noticeDesc(actions));
+	return `${PRODUCT}  ${verbs.join(" · ")}  ${fmtK(first.tokensBefore)} → ${fmtK(last.tokensAfter)}${tail.length ? "  " + tail.join(" · ") : ""}`;
 }
 
 export interface NoticeTheme {
 	fg(color: string, text: string): string;
+	bold?(text: string): string;
 }
 
-const MARK = "▸ ";
-const INDENT = " ".repeat(MARK.length + PRODUCT.length + 2);
+/** Detail lines sit under the words, after the monogram and its space. */
+const INDENT = " ".repeat(SYM.length + 1);
+const GAP = "   ";
+/** Waiting at least this long is a cost the user paid: it gets the warning colour. Shorter waits are not worth the eye. */
+const WAIT_NOTICEABLE_MS = 2000;
 
-/** Lines for the transcript. Narrow terminals drop whole segments in order (description, then bar); the numbers always stay.
+/**
+ * "ƶ zipped 12 old outputs   74K → 43K   6 ms"
+ * Colour, by meaning (theme tokens only, so dark/light/custom themes keep working; monochrome still reads):
+ *   accent  the monogram (bold): whose line it is
+ *   muted   the words: what happened
+ *   success the size now (bold): the one bright thing on the line
+ *   dim     the old size, the arrow, durations, "ready while you were away", the detail lines
+ *   warning only a wait the user actually sat through (>= 2 s): the one thing pi-zip cost them
+ */
+export function colorTail(tail: string[], th: NoticeTheme): string {
+	return tail.map((part) => {
+		const waited = /^waited ([\d.]+) s$/.exec(part);
+		return th.fg(waited && Number(waited[1]) * 1000 >= WAIT_NOTICEABLE_MS ? "warning" : "dim", part);
+	}).join(th.fg("dim", " · "));
+}
+
+/** Lines for the transcript. Narrow terminals drop whole segments in order (tail, then words); 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 b = fmtK(d.before), a = fmtK(d.after);
+	const nums = `${b} → ${a}`;
+	const strong = (t: string) => (th.bold ? th.bold(t) : t);
+	const numsC = `${th.fg("dim", b)}${th.fg("dim", " → ")}${th.fg("success", strong(a))}`;
+	const { verbs, tail } = splitDesc(d.desc);
+	const said = verbs.join(" · "), saidC = verbs.map((v) => th.fg("muted", v)).join(th.fg("dim", " · "));
+	const tailP = tail.join(" · "), tailC = colorTail(tail, th);
+	const mark = brand(th);
 	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)],
+		...(said && tailP ? [[`${SYM} ${said}${GAP}${nums}${GAP}${tailP}`, `${mark} ${saidC}${GAP}${numsC}${GAP}${tailC}`] as [string, string]] : []),
+		...(said ? [[`${SYM} ${said}${GAP}${nums}`, `${mark} ${saidC}${GAP}${numsC}`] as [string, string]] : []),
+		[`${SYM} ${nums}`, `${mark} ${numsC}`],
+		[nums, numsC],
 	];
 	const head = tries.find(([plain]) => w(plain) <= width);
 	if (!head) return [];
 	const out = [head[1]];
+	const fit = (plain: string) => (w(INDENT + plain) <= width ? INDENT : w(plain) <= width ? "" : null);
 	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));
+		const ind = fit(plain);
+		if (ind !== null) out.push(th.fg("dim", ind + plain));
 	};
-	if (d.first) sub("originals are kept; the model can recall any of them with zip_recall");
+	if (d.first) sub("originals are kept · the model can unzip any of them");
 	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)));
+	const lw = Math.min(32, 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}`);
+		const size = fmtK(i.tokens).padStart(6);
+		const plain = `${label}${size}   ${i.handle}`;
+		const ind = fit(plain);
+		if (ind === null) continue;
+		// an item row: what it was (muted, like the words above), how big and its handle (dim: there if you need it)
+		out.push(th.fg("dim", ind) + th.fg("muted", label) + th.fg("dim", size) + th.fg("dim", `   ${i.handle}`));
 	}
 	if (d.more) sub(`… ${d.more} more`);
+	if (d.why) sub(d.why);
 	return out;
 }
 
@@ -126,27 +173,38 @@ export interface ZipControl {
 	card?(ctx?: Any): CardData;
 	/** Show a /zip result in the transcript; false = no transcript surface here (print/json/rpc or an older Pi). */
 	show?(ctx: Any, data: NoticeData): boolean;
-	statsLine(ctx?: Any): string;
 	setOff(off: boolean): string;
 	toggleQuiet(): string;
 }
 
+const ZIP_SUBS: [string, string][] = [
+	["off", "stop folding; requests left untouched"],
+	["on", "resume folding"],
+	["quiet", "toggle the per-turn notice"],
+];
+
 export function registerZipCommand(pi: ExtensionAPI, zip: ZipControl) {
 	pi.registerCommand("zip", {
-		description: `${PRODUCT}: status | off | on | quiet`,
+		description: `${PRODUCT}: off | on | quiet`,
+		getArgumentCompletions: (prefix: string) => {
+			const p = (prefix ?? "").trim().toLowerCase();
+			const items = ZIP_SUBS.filter(([v]) => v.startsWith(p)).map(([value, description]) => ({ value, label: value, description }));
+			return items.length ? items : null;
+		},
 		handler: async (args: string, cctx: Any) => {
-			const sub = (args ?? "").trim().toLowerCase() || "status";
-			if ((sub === "status" || sub === "stats") && zip.card && zip.show) {
+			// "/zip" alone shows the card. "status" and "stats" are older spellings of the same thing: still accepted, never advertised.
+			const raw = (args ?? "").trim().toLowerCase();
+			const sub = raw === "" || raw === "stats" ? "status" : raw;
+			if (sub === "status" && zip.card && zip.show) {
 				const card = zip.card(cctx);
 				if (zip.show(cctx, { v: 2, kind: "card", card, text: zip.status(cctx), before: 0, after: 0, desc: "" })) return;
 			}
 			const text =
 				sub === "status" ? zip.status(cctx)
-				: sub === "stats" ? zip.statsLine(cctx)
 				: sub === "off" ? zip.setOff(true)
 				: sub === "on" ? zip.setOff(false)
 				: sub === "quiet" ? zip.toggleQuiet()
-				: `${PRODUCT}: unknown subcommand "${sub}" (use status | off | on | quiet)`;
+				: `${PRODUCT}: unknown subcommand "${sub}" (use /zip, or /zip off | on | quiet)`;
 			if (zip.show && (sub === "off" || sub === "on" || sub === "quiet")) {
 				const word: StateWord = sub === "quiet" ? (/notices off/.test(text) ? "quiet" : "notices on") : sub;
 				const reason = text.replace(/^pi-zip: (off|on)\.? ?/, "").replace(/^pi-zip: /, "");

package/src/placeholder.ts

@@ -1,6 +1,7 @@
 // Placeholders (F2): tool + args + size + key lines + handle. Handles are deterministic in the session entry id.
 import { createHash } from "node:crypto";
 import type { Block, Calls } from "./plan.ts";
+import { type FileRecall, fileRecallHow } from "./recallfile.ts";
 import { type Any, clip, textOf } from "./util.ts";
 
 export const PH_MARK = "[folded by pi-zip";
@@ -67,7 +68,11 @@ export function shortArgs(args: Any): string {
 	if (typeof args.command === "string") return clipMid(args.command, ARG_CHARS);
 	const path = typeof args.path === "string" ? args.path : typeof args.file_path === "string" ? args.file_path : null;
 	if (path !== null && typeof args.pattern !== "string") {
-		const win = ["offset", "limit"].filter((k) => typeof args[k] === "number" && Number.isFinite(args[k])).map((k) => ` ${k}=${args[k]}`).join(""); // which slice of the file
+		// which slice of the file, written the way Pi's own read row writes it: "src/a.ts:1-2000", "src/a.ts:50-"
+		const num = (k: string) => (typeof args[k] === "number" && Number.isFinite(args[k]) ? (args[k] as number) : undefined);
+		const off = num("offset"), lim = num("limit");
+		const start = off ?? 1;
+		const win = off !== undefined || lim !== undefined ? `:${start}${lim !== undefined ? `-${start + lim - 1}` : ""}` : "";
 		return clipMid(path, ARG_CHARS) + win;
 	}
 	if (typeof args.pattern === "string") return clipMid(args.pattern + (args.path ? " " + args.path : ""), ARG_CHARS);
@@ -109,6 +114,7 @@ export interface PlaceholderMeta {
 	turn?: number; // user turn the output belongs to (1-based, as seen in the projection when it was folded)
 	isError?: boolean;
 	noRecall?: boolean; // zip_recall is not declared to the model (`--tools` allowlist): point at re-reading instead
+	file?: FileRecall; // ... but read, grep or bash is: point at the recall file (written on demand from the session)
 }
 
 /** Placeholder text, or null when the output is too short to be worth folding. The text is stored with the fold (context_edit),
@@ -122,17 +128,19 @@ export function makePlaceholder(text: string, tool: string, args: string, handle
 	return (
 		`${PH_MARK} · ${tool}${args ? " " + args : ""}${meta.turn ? ` · turn ${meta.turn}` : ""}${outcome ? ` · ${outcome}` : ""} · ${text.length} chars, ${lines} lines · handle ${handle}]\n` +
 		(keys.length ? `key lines kept (original line numbers; up to ${keep}):\n${body}\n` : "") +
-		(!meta.noRecall
+		(meta.file
+			? `Original kept byte for byte, even after summaries or compaction, in ${meta.file.dir}/${handle}.txt: ${fileRecallHow(meta.file)}; prefer that to re-running or re-reading the source (output may differ). Do not guess its content.`
+			: !meta.noRecall
 			? `Original kept byte for byte, recallable even after summaries or compaction: ${RECALL_TOOL}("${handle}") (optional grep/range) is instant, free, no side effects; prefer it to re-running or re-reading (output may differ). Do not guess its content.`
 			: `Original not shown (${RECALL_TOOL} is not enabled in this session): re-read the file or re-run the read-only command if you need it. Do not guess its content.`)
 	);
 }
 
 /** Placeholder for a toolResult block (null for image results, entries without an id, or short outputs). */
-export function makePlaceholderFor(b: Block, calls: Calls, keep = 8, noRecall = false): string | null {
+export function makePlaceholderFor(b: Block, calls: Calls, keep = 8, noRecall = false, file?: FileRecall): string | null {
 	const content = b.msg.content;
 	if (Array.isArray(content) && content.some((c: Any) => c?.type !== "text")) return null;
 	if (!b.entryId) return null;
 	const call = calls.get(b.msg.toolCallId);
-	return makePlaceholder(textOf(content), call?.name ?? b.msg.toolName ?? "tool", call ? shortArgs(call.args) : "", handleFor(b.entryId), keep, { turn: b.userTurn, isError: !!b.msg.isError, noRecall });
+	return makePlaceholder(textOf(content), call?.name ?? b.msg.toolName ?? "tool", call ? shortArgs(call.args) : "", handleFor(b.entryId), keep, { turn: b.userTurn, isError: !!b.msg.isError, noRecall, file });
 }