pi-zip 0.2.0 → 0.2.2

package/README.md

@@ -29,6 +29,7 @@ Known limits:
 
 - **GLM** (automatic prefix cache that outlives its declared 5 minutes): v0.1 cost about 1.2× BC live. v0.2 learns the real cache lifetime and folds the previous turn after the declared TTL (offline 0.95–0.97× v0.1), but this was not verified live.
 - **Long autonomous runs** (one prompt, hundreds of tool calls, e.g. sub-agents): roughly on par with BC, not better. Outputs are only folded inside a running turn once they are 60 requests old.
+- **Tool allowlists** (`pi --tools read,bash`, and sub-agent launchers that pass one): Pi then hides `zip_recall`, so pi-zip folds only outputs the model can re-read (files, read-only commands) and the placeholder says to re-read. Add `zip_recall` to the list to get full folding.
 - If you always answer within the cache lifetime, there is little to save, by design.
 
 ## What you see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-zip",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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,6 +1,7 @@
 // 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 { RECALL_TOOL } from "./placeholder.ts";
 import { registerRecallTool } from "./recall.ts";
 import { Zip } from "./run.ts";
 
@@ -9,8 +10,24 @@ export default function piZip(pi: ExtensionAPI) {
 	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);
-	pi.on("session_start", (_e, ctx) => zip.sessionStart(ctx));
-	pi.on("before_agent_start", (_e, ctx) => zip.beforeAgentStart(ctx));
+	// 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 = () => {
+		try {
+			const active = pi.getActiveTools?.();
+			if (Array.isArray(active)) zip.setRecallOk(active.includes(RECALL_TOOL));
+		} catch {
+			/* never in the way */
+		}
+	};
+	pi.on("session_start", (_e, ctx) => {
+		checkRecall();
+		return zip.sessionStart(ctx);
+	});
+	pi.on("before_agent_start", (_e, ctx) => {
+		checkRecall();
+		return zip.beforeAgentStart(ctx);
+	});
 	pi.on("context_with_system", (e, ctx) => zip.context(e, ctx)); // the complete transcript: system messages stay where Pi put them
 	pi.on("turn_end", (e, ctx) => zip.turnEnd(e, ctx));
 	pi.on("agent_before_settle", (e, ctx) => zip.settle(e, ctx));

package/src/placeholder.ts

@@ -108,6 +108,7 @@ export function outcomeHint(text: string, tool: string, isError?: boolean): stri
 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
 }
 
 /** Placeholder text, or null when the output is too short to be worth folding. The text is stored with the fold (context_edit),
@@ -121,15 +122,17 @@ 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` : "") +
-		`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.`
+		(!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): string | null {
+export function makePlaceholderFor(b: Block, calls: Calls, keep = 8, noRecall = false): 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 });
+	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 });
 }

package/src/plan.ts

@@ -282,6 +282,8 @@ 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)
 }
 
@@ -366,7 +368,7 @@ export function planContext(entries: Any[], o: PlanOpts): PlanResult | null {
 	};
 	const addFold = (b: Block, trig: string): boolean => {
 		if (tokOverride.has(b.idx) || recalled.has(handleFor(b.entryId!))) return false; // F4: never refold what the model recalled
-		const ph = makePlaceholderFor(b, calls, keepLines);
+		const ph = makePlaceholderFor(b, calls, keepLines, !!o.rereadOnly);
 		if (ph === null) return false;
 		const phTok = tok4(ph);
 		if (!(phTok < 0.9 * b.tokens)) return false;
@@ -384,7 +386,7 @@ export function planContext(entries: Any[], o: PlanOpts): PlanResult | null {
 	const head = law.pr?.cls === "automatic" ? MIN_EXPECT / k : 0;
 	const start: number[] = [];
 	blocks.reduce((acc, b) => ((start[b.idx] = acc), acc + b.tokens), o.sys);
-	const foldable = (b: Block) => b.kind === "toolResult" && !b.edited && !!b.entryId && b.tokens > foldMin && !isRecall(b) && start[b.idx] >= head;
+	const foldable = (b: Block) => b.kind === "toolResult" && !b.edited && !!b.entryId && b.tokens > foldMin && !isRecall(b) && start[b.idx] >= head && (!o.rereadOnly || classify(b) === "rereadable");
 	const protectedTurn = (b: Block) => b.userTurn >= userTurns - PROTECT_USER_TURNS + 1;
 	const savings = () => folds.reduce((a, t) => a + t.entryTokens - t.phTokens, 0);
 	const cands = blocks.filter((b) => foldable(b) && !protectedTurn(b));
@@ -416,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;
@@ -435,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

@@ -92,6 +92,15 @@ export class Zip implements ZipControl {
 
 	active = () => !this.off && !this.conflict;
 
+	/** 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;
+	}
+
 	ledger(rec: Record<string, unknown>) {
 		const path = process.env.PI_ZIP_LEDGER; // test only
 		if (!path) return;
@@ -139,7 +148,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, 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 {
@@ -227,6 +236,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;
@@ -505,6 +515,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