pi-zip 0.2.1 → 0.2.4

package/README.md

@@ -61,8 +61,8 @@ The cold cap is kept below Pi's own compaction trigger (window minus `compaction
 
 | Command | Effect |
 |---|---|
-| `/zip status` | on / off / paused, cache TTL, totals |
-| `/zip stats` | tokens folded, estimated $ saved versus doing nothing, summaries, recalls |
+| `/zip status` | on / off / paused, cache TTL, what this session has folded, summarised and recalled, learned cache survival |
+| `/zip stats` | this session's folds (with tokens removed), summaries and recalls; persisted in the session, so a restart does not reset them |
 | `/zip off` | strict no-op: no folds, no summaries, requests left untouched (earlier folds stay recallable) |
 | `/zip on` | resume |
 | `/zip quiet` | toggle the per-turn notice (folding continues) |
@@ -109,9 +109,9 @@ The guard has two parts. Before saving a fold or a summary it checks that the ed
 
 ## FAQ
 
-**Will it save money?** Mostly on cold returns, which is where a long session pays for a full cache rewrite. While the cache is warm it edits only when the inequality above says the rewrite pays back (large contexts, near Pi's compaction trigger, outputs 60+ requests old). `/zip stats` shows an estimate based on the model's declared prices: avoided cache writes and reads, minus summary calls, minus the cost of content you recalled. It is an estimate (token counts are chars/4, scaled by the calibration above), and it can be negative.
+**Will it save money?** Mostly on cold returns, which is where a long session pays for a full cache rewrite. While the cache is warm it edits only when the inequality above says the rewrite pays back (large contexts, near Pi's compaction trigger, outputs 60+ requests old). `/zip stats` shows what this session has folded (and roughly how many tokens that removed), its summaries with what their model calls cost, and its recalls. The numbers live in the session file, so a restart does not reset them.
 
-**Does it cost extra?** Planning is free. A summary is one extra model call (the current model, no tools, no prompt cache), shown in `/zip stats`. A background summary you never use (you came back while the cache was warm) is counted too. Recalled content re-enters the context at normal prices.
+**Does it cost extra?** Planning is free. A summary is one extra model call (the current model, no tools, no prompt cache), shown in `/zip stats`. A background summary you never use (you came back while the cache was warm) is counted there too. Recalled content re-enters the context at normal prices.
 
 **Can the model lose information?** Folded outputs are replaced by a placeholder with key lines and a handle, and the placeholder tells the model not to guess. Summaries quote your requests verbatim and never paraphrase the model's reasoning. If the model ignores the handle and guesses, that is a model failure pi-zip cannot catch; this is why only re-readable outputs of the previous turn are folded at a cold return; other outputs of the protected turns wait until they are 60 requests old.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-zip",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "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/notice.ts

@@ -27,12 +27,6 @@ export function noticeText(actions: NoticeAction[]): string {
 	return `${PRODUCT} · ${segs.join(" · ")}`;
 }
 
-/** Prices are $ per million tokens, as declared by the model. */
-export interface Prices {
-	cacheWrite: number;
-	cacheRead: number;
-}
-
 export class Stats {
 	folds = 0; // outputs folded
 	foldedTokens = 0; // tokens removed by folds (estimate: chars/4)
@@ -49,37 +43,11 @@ export class Stats {
 	activeSaved = 0; // tokens currently removed from the context by our edits
 	notices = 0;
 
-	/** Estimated $ saved versus doing nothing: avoided cache writes and reads, minus summary calls, recalled content re-entering the context, and warm-valve rewrites. */
-	savedUsd(p: Prices | null): number | null {
-		if (!p) return null;
-		const gross = (this.writeSavedTokens * p.cacheWrite + this.readSavedTokens * p.cacheRead) / 1e6;
-		const recall = (this.recallChars / 4) * p.cacheWrite / 1e6;
-		const pressure = this.pressureRewriteTokens * Math.max(p.cacheWrite - p.cacheRead, 0) / 1e6;
-		return gross - this.summaryUsd - recall - pressure;
-	}
-}
-
-export const pricesOf = (model: Any): Prices | null => {
-	const c = model?.cost;
-	const cw = c?.cacheWrite > 0 ? c.cacheWrite : c?.input > 0 ? c.input : 0;
-	const cr = c?.cacheRead > 0 ? c.cacheRead : cw * 0.1;
-	return cw > 0 ? { cacheWrite: cw, cacheRead: cr } : null;
-};
-
-export function statsText(s: Stats, model: Any): string {
-	const usd = s.savedUsd(pricesOf(model));
-	const money = usd === null ? "n/a (model declares no prices)" : `${usd < 0 ? "-" : ""}$${Math.abs(usd).toFixed(usd !== 0 && Math.abs(usd) < 0.1 ? 4 : 2)}`;
-	return (
-		`${PRODUCT} stats (since pi started): folded ${s.folds} output${s.folds === 1 ? "" : "s"} (${fmtK(s.foldedTokens)} tokens), ` +
-		`${s.summaries} summar${s.summaries === 1 ? "y" : "ies"} (${fmtK(s.summarizedTokens)} tokens, ${(s.summaryMs / 1000).toFixed(1)} s waited, $${s.summaryUsd.toFixed(4)}), ` +
-		`${s.recalls} recall${s.recalls === 1 ? "" : "s"} (~${fmtK(s.recallChars / 4)} tokens re-read). ` +
-		`Estimated saved vs doing nothing: ${money}, counting avoided cache writes and reads minus summary calls, recalled content and warm-valve rewrites; token counts are chars/4 estimates.`
-	);
 }
 
 export interface ZipControl {
-	status(): string;
-	statsLine(): string;
+	status(ctx?: Any): string;
+	statsLine(ctx?: Any): string;
 	setOff(off: boolean): string;
 	toggleQuiet(): string;
 }
@@ -90,8 +58,8 @@ export function registerZipCommand(pi: ExtensionAPI, zip: ZipControl) {
 		handler: async (args: string, cctx: Any) => {
 			const sub = (args ?? "").trim().toLowerCase() || "status";
 			const text =
-				sub === "status" ? zip.status()
-				: sub === "stats" ? zip.statsLine()
+				sub === "status" ? zip.status(cctx)
+				: sub === "stats" ? zip.statsLine(cctx)
 				: sub === "off" ? zip.setOff(true)
 				: sub === "on" ? zip.setOff(false)
 				: sub === "quiet" ? zip.toggleQuiet()

package/src/plan.ts

@@ -282,6 +282,7 @@ export interface PlanOpts {
 	relax?: boolean; // default RELAX_PREV_TURN
 	minGain?: number;
 	inturnAge?: number; // default settings().inturnAge (PI_ZIP_INTURN_AGE, 60); 0 = outputs of the protected turns never fold on age
+	noSummary?: boolean; // a summary was already made while this cache stayed warm: no second one unless the context is at/above the compaction room
 	rereadOnly?: boolean; // zip_recall is not available to the model: fold only outputs that can be re-read (classify "rereadable")
 	pastTtl?: boolean; // a user return after the declared TTL: a warm plan may relax into the previous user turn too (RELAX_PREV_TURN)
 }
@@ -417,7 +418,13 @@ export function planContext(entries: Any[], o: PlanOpts): PlanResult | null {
 		}
 	}
 	let ctxAfterFolds = ctxEst - savings();
-	const sumTrigger: "cold" | "valve" | null = ctxAfterFolds > coldCap ? trig : null;
+	// what no summary can remove: the system prompt, the protected turns (after their folds) and the previous summary, which the next
+	// one carries forward; the cap is never chased below it (a context that is mostly this floor would be re-summarised for nothing)
+	const prevSum = blocks[0]?.kind === "summary" ? blocks[0].tokens : 0;
+	const floor = o.sys + prevSum + blocks.reduce((a, b) => a + (protectedTurn(b) ? (tokOverride.get(b.idx) ?? b.tokens) : 0), 0);
+	const target = Math.max(coldCap, floor + SUMMARY_FLOOR);
+	const atRoom = room !== null && k * ctxAfterFolds >= room;
+	const sumTrigger: "cold" | "valve" | null = ctxAfterFolds > target && (!o.noSummary || atRoom) ? trig : null;
 	let cutIdx: number | null = null;
 	let prefixTokens = 0;
 	let summaryTokensPlanned = 0;
@@ -436,7 +443,7 @@ export function planContext(entries: Any[], o: PlanOpts): PlanResult | null {
 			acc += tokOverride.get(i) ?? blocks[i].tokens;
 		}
 		const total = o.sys + acc;
-		const S = (x: number) => clamp(SUMMARY_RATIO * x, SUMMARY_FLOOR, SUMMARY_CAP);
+		const S = (x: number) => Math.max(clamp(SUMMARY_RATIO * x, SUMMARY_FLOOR, SUMMARY_CAP), prevSum); // the next summary carries the previous one forward
 		if (cuts.length) {
 			let pick = cuts[cuts.length - 1];
 			for (const c of cuts) if (total - pre[c] + S(pre[c]) <= coldCap) { pick = c; break; }

package/src/run.ts

@@ -6,16 +6,17 @@ 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 { Stats, noticeText, statsText, type NoticeAction, type ZipControl } from "./notice.ts";
+import { fmtK, Stats, noticeText, type NoticeAction, 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 } from "./placeholder.ts";
+import { handleFor, PH_MARK, RECALL_TOOL } from "./placeholder.ts";
 import { recalledHandlesFromBranch } from "./recall.ts";
 import { buildCut } from "./summary.ts";
-import { type Any, PRODUCT, tok4 } from "./util.ts";
+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";
+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.
 const CONFLICT_RE = /billion-context|bc-pi|magic-context|smart-compact|hot-compact|context-prune|pi-vcc|context-mode|prefix-cache/i;
@@ -94,6 +95,8 @@ 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;
+	/** 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) {
 		if (ok !== this.recallOk) this.ledger({ type: "recall_available", ok });
 		this.recallOk = ok;
@@ -146,7 +149,7 @@ export class Zip implements ZipControl {
 	private opts(ctx: Any, pending: boolean, mode: "cold" | "warm", entries: Any[], pWarm = mode === "cold" ? 0 : 1): { o: PlanOpts; cal: Calibration } {
 		const sys = this.sysTokens(ctx);
 		const cal = calibrate(entries, sys);
-		return { cal, o: { mode, sys, k: cal.k, cwd: (ctx?.cwd as string) ?? process.cwd(), recalled: this.recalled, model: ctx?.model, promptPending: pending, rereadOnly: !this.recallOk, reserve: this.reserve(ctx), steerIds: this.steerIds, law: this.law(ctx, pWarm), trace: [] } };
+		return { cal, o: { mode, sys, k: cal.k, cwd: (ctx?.cwd as string) ?? process.cwd(), recalled: this.recalled, model: ctx?.model, promptPending: pending, rereadOnly: !this.recallOk, noSummary: mode === "warm" && this.summarizedWarm, reserve: this.reserve(ctx), steerIds: this.steerIds, law: this.law(ctx, pWarm), trace: [] } };
 	}
 
 	private law(ctx: Any, pWarm: number): Law {
@@ -234,6 +237,7 @@ export class Zip implements ZipControl {
 		if (!this.prevKey) ({ key: this.prevKey, total: this.prevTotal } = lastPrompt(branch)); // fresh process: the session's newest response
 		const { cold, reason, ttl, pWarm: p, src, gapS, pastTtl } = detectCold(ctx.model, this.lastReqMs, branch, Date.now(), this.lastModelKey, (g, prior) => pWarm(this.ent, g, prior));
 		this.cold = cold;
+		if (cold) this.summarizedWarm = false; // a cold return may summarise again
 		this.pastTtl = pastTtl;
 		this.pWarm = p;
 		this.survSrc = src;
@@ -267,7 +271,13 @@ export class Zip implements ZipControl {
 		this.bg = null;
 		if (!b) return;
 		if (!b.done) b.controller.abort();
-		b.promise.then((c) => { if (c) this.stats.summaryUsd += c.costUsd; });
+		b.promise.then((c) => {
+			if (!c) return;
+			this.stats.summaryUsd += c.costUsd;
+			try {
+				this.pi.appendEntry(UNUSED_SUMMARY_CUSTOM, { usd: c.costUsd });
+			} catch {}
+		});
 	}
 
 	async context(e: Any, ctx: Any): Promise<Any> {
@@ -512,6 +522,7 @@ export class Zip implements ZipControl {
 			return undefined;
 		}
 		const bad = checkEdits(o.blocks, o.userTurns, live, cut);
+		if (!bad && cut) this.summarizedWarm = true; // one summary per warm stretch (two in a row cost two uncached calls; the second gains little)
 		if (bad) {
 			this.ledger({ type: "guard_drop", turnIndex: e.turnIndex, reason: bad, folds: live.length, source: plan.source });
 			plan.persisted = false; // keep the request-local view: never switch the fold set mid-run
@@ -632,16 +643,35 @@ export class Zip implements ZipControl {
 			this.pi.appendEntry(STATE_CUSTOM, { off: this.off, quiet: this.quiet });
 		} catch {}
 	}
-	status(): string {
+	/** What this session carries: folds and summaries persisted in its file (they survive restarts) and the recalls in its branch. */
+	private sessionTotals(ctx: Any): string {
+		const branch = ctx ? this.branch(ctx) : [];
+		const byId = new Map(branch.map((e: Any) => [e?.id, e]));
+		let folds = 0, folded = 0, summaries = 0, recalls = 0, usd = 0;
+		for (const e of branch) {
+			const ph = String(e?.replacement?.content?.[0]?.text ?? "");
+			if (e?.type === "context_edit" && ph.startsWith(PH_MARK)) {
+				folds++;
+				folded += Math.max(0, textOf(byId.get(e.targetId)?.message?.content).length - ph.length) / 4;
+			} else if (e?.type === "compaction" && e.details?.by === PRODUCT) {
+				summaries++;
+				usd += Number(e.usage?.cost?.total) || 0;
+			} else if (e?.type === "custom" && e.customType === UNUSED_SUMMARY_CUSTOM) usd += Number(e.data?.usd) || 0;
+			else if (e?.type === "message" && e.message?.role === "toolResult" && e.message?.toolName === RECALL_TOOL) recalls++;
+		}
+		const n = (x: number, one: string, many: string) => `${x} ${x === 1 ? one : many}`;
+		return `this session: ${n(folds, "folded output", "folded outputs")} (~${fmtK(folded)} tokens), ${n(summaries, "summary", "summaries")}${usd > 0 ? ` (summary calls $${usd.toFixed(4)})` : ""}, ${n(recalls, "recall", "recalls")}`;
+	}
+	status(ctx?: Any): string {
 		const state = this.off ? "off" : this.conflict ? `paused ("${this.conflict}" also manages context; only the request guard is on)` : "on";
 		const key = modelKey(this.model), ttl = ttlFor(this.model), ent = loadStats().models[key];
 		const pr = lawPrices(ent?.cls, ttl >= 3_600_000);
 		const cache = !key ? "" : `\ncache ${key}: ${pr ? `${pr.cls} (from usage)` : "class unknown until the first response"}` +
 			`, ${pr ? `read ${+pr.r.toFixed(4)} / write ${+pr.w.toFixed(4)} / output ${+pr.out.toFixed(4)} x input (class ratios)` : "no prices (legacy rule)"}` +
 			`, ${describe(ent, ttl / 1000)}, growth ${(this.g / 1000).toFixed(1)}K/request`;
-		return `${PRODUCT}: ${state}, cache TTL ${Math.round(ttl / 1000)} s, ${this.quiet ? "notices off, " : ""}folded ${this.stats.folds} output${this.stats.folds === 1 ? "" : "s"}, ${this.stats.summaries} summar${this.stats.summaries === 1 ? "y" : "ies"} (/zip stats for details)${cache}`;
+		return `${PRODUCT}: ${state}, cache TTL ${Math.round(ttl / 1000)} s, ${this.quiet ? "notices off, " : ""}${this.sessionTotals(ctx)}${cache}`;
 	}
-	statsLine = () => statsText(this.stats, this.model);
+	statsLine = (ctx?: Any) => `${PRODUCT} ${this.sessionTotals(ctx)} (token counts are chars/4 estimates)`;
 	setOff(off: boolean): string {
 		this.off = off;
 		if (off) { this.runPlan = null; this.runEdits = false; this.cancelTimer(); this.discardBg(); }