pi-context-guard-jev 0.2.0 → 0.3.1

package/src/checkpoint.ts

@@ -10,8 +10,9 @@
  * entries), never kept in memory: a boundary's drafts can be replaced by a later handler or rejected
  * as a whole, and /tree or compaction change the branch.
  */
-import { toolLabel } from "./render.ts";
-import { type Candidate, type CollectOptions, candidateOf, collectHistory, findRunStart, indexSpan, questionAt, type RunHistory, type ToolCallInfo } from "./run.ts";
+import { RECALL_TOOL, toolLabel } from "./render.ts";
+import { type Candidate, type CollectOptions, candidateOf, collectHistory, findRunStart, isBranchSteering, indexSpan, lastUserIndex, type RunHistory, runQuestion, type ToolCallInfo } from "./run.ts";
+import { contentChars } from "./size.ts";
 import type { ProjectedEntryLike } from "./types.ts";
 
 export interface CheckpointOptions extends CollectOptions {
@@ -116,7 +117,8 @@ export function collectCheckpoint(entries: readonly ProjectedEntryLike[], option
 	for (const entry of span) {
 		const candidate = candidateOf(entry, toolCalls, options);
 		if (!candidate || candidate.turn === undefined || judged.has(candidate.entryId)) continue;
-		if (candidate.turn > youngest) continue;
+		// A recall output was asked for in this run: judging it again mid-run made models recall the recall.
+		if (candidate.turn > youngest || candidate.toolName === RECALL_TOOL) continue;
 		const turn = candidate.turn;
 		const superseded = supersededBy({ toolName: candidate.toolName, args: candidate.args, turn }, calls);
 		candidates.push({ ...candidate, turn, laterCalls: laterCallsFor(turn, calls), ...(superseded ? { superseded } : {}) });
@@ -124,7 +126,7 @@ export function collectCheckpoint(entries: readonly ProjectedEntryLike[], option
 
 	const latest = assistantTexts.at(-1)?.text ?? "";
 	return {
-		question: questionAt(entries, start),
+		question: runQuestion(entries, start),
 		history: collectHistory(entries.slice(0, start), options.historyExchanges),
 		latest,
 		notes: assistantTexts
@@ -156,14 +158,16 @@ export function paysOff(pendingChars: number, turnsSoFar: number, rewriteChars:
 	return pendingChars * Math.max(1, turnsSoFar) >= factor * rewriteChars;
 }
 
-/** Characters of model-visible text in the projected context (an estimate of its size). */
+/**
+ * Size of the projected context in text characters (an estimate, see size.ts: images count by their
+ * pixels, not their base64 length).
+ */
 export function contextChars(entries: readonly ProjectedEntryLike[]): number {
 	let n = 0;
 	for (const entry of entries) {
 		for (const message of entry.messages) {
 			if (typeof message.summary === "string") n += message.summary.length;
-			if (typeof message.content === "string") n += message.content.length;
-			else for (const block of message.content ?? []) n += typeof block.text === "string" ? block.text.length : JSON.stringify(block).length;
+			n += contentChars(message.content);
 		}
 	}
 	return n;
@@ -187,7 +191,7 @@ export type BranchEntry = {
 	customType?: string;
 	data?: unknown;
 	targetId?: string;
-	message?: { role?: string; stopReason?: string; toolCallId?: string };
+	message?: { role?: string; stopReason?: string; toolCallId?: string; content?: unknown };
 };
 
 const isAnswered = (entry: BranchEntry): boolean =>
@@ -337,7 +341,8 @@ export function refreshOnReadThrough(
 	baseline: number,
 ): string[] {
 	if (!(cacheRead > 0) || !(baseline > 0) || cacheRead <= baseline) return [];
-	const start = findRunStart(projection);
+	// The baseline is measured from the last user message (prompt or steering message, see runBaseline).
+	const start = lastUserIndex(projection);
 	if (start < 0) return [];
 	const position = positionsOf(branch);
 	const refreshed: string[] = [];
@@ -391,10 +396,12 @@ export function anthropicRewriteChars(
 	const read = Number.isFinite(first) ? trustedReadPoint(branch, log, model, now, first) : undefined;
 	const readIndex = read ? projection.findIndex((entry) => entry.sourceEntry.id === read.id) : -1;
 	if (readIndex >= 0) return contextChars(projection.slice(readIndex + 1));
-	// The question pin can be read only if every edit comes after it (an omitted old exchange comes before).
-	const runStart = findRunStart(projection);
+	// The question pin (on the last user message with text: after steering, the steering message) can be
+	// read only if every edit comes after it (an omitted old exchange, or an output from before a steering
+	// message, comes before).
+	const pin = lastUserIndex(projection);
 	const earliest = projection.findIndex((entry) => candidateIds.has(entry.sourceEntry.id));
-	const from = earliest >= 0 && earliest <= runStart ? 0 : runStart + 1;
+	const from = earliest >= 0 && earliest <= pin ? 0 : pin + 1;
 	return contextChars(projection.slice(Math.max(0, from)));
 }
 
@@ -416,12 +423,28 @@ export function memoFromBranch(branch: readonly BranchEntry[], customType: strin
 }
 
 /**
- * Old exchanges judged during the current run (records of any phase after the last user message on the
- * branch). An exchange is judged again in a later run, against that run's work.
+ * Index of the branch entry with the user message that started the current run (steering messages
+ * skipped, as in run.ts → findRunStart), or -1.
  */
-export function exchangeMemo(branch: readonly BranchEntry[], customType: string): Set<string> {
+export function branchRunStart(branch: readonly BranchEntry[]): number {
+	const isUser = (e: BranchEntry) => e.type === "message" && e.message?.role === "user";
 	let start = branch.length - 1;
-	while (start >= 0 && !(branch[start].type === "message" && branch[start].message?.role === "user")) start--;
+	while (start >= 0 && !isUser(branch[start])) start--;
+	while (start > 0 && isBranchSteering(branch, start)) {
+		let p = start - 1;
+		while (p >= 0 && !isUser(branch[p])) p--;
+		if (p < 0) break;
+		start = p;
+	}
+	return start;
+}
+
+/**
+ * Old exchanges judged during the current run (records of any phase after the user message that started
+ * the run on the branch). An exchange is judged again in a later run, against that run's work.
+ */
+export function exchangeMemo(branch: readonly BranchEntry[], customType: string): Set<string> {
+	const start = branchRunStart(branch);
 	const judged = new Set<string>();
 	for (const entry of branch.slice(start + 1)) {
 		if (entry.type !== "custom" || entry.customType !== customType) continue;

package/src/config.ts

@@ -80,6 +80,11 @@ export interface GuardConfig {
 	exchangeBreakEven: boolean;
 	/** A pass omits exchanges only if they save at least this many characters together (when that costs a cache rewrite). */
 	exchangeMinSavingChars: number;
+	/**
+	 * Remove images from tool results once they are this many turns old (assistant messages after the
+	 * result); `recall` shows them again. Images in user messages are always kept. 0 turns this off.
+	 */
+	imageKeepTurns: number;
 }
 
 export const DEFAULT_CONFIG: GuardConfig = {
@@ -114,6 +119,7 @@ export const DEFAULT_CONFIG: GuardConfig = {
 	exchangeOmitThreshold: 0.2,
 	exchangeBreakEven: true,
 	exchangeMinSavingChars: 8_000,
+	imageKeepTurns: 3,
 };
 
 const NUMBER_RANGES: Partial<Record<keyof GuardConfig, [number, number]>> = {
@@ -138,9 +144,10 @@ const NUMBER_RANGES: Partial<Record<keyof GuardConfig, [number, number]>> = {
 	keepRecentExchanges: [0, 100],
 	exchangeOmitThreshold: [0, 1],
 	exchangeMinSavingChars: [0, 10_000_000],
+	imageKeepTurns: [0, 1_000],
 };
 
-const INTEGER_KEYS = new Set<keyof GuardConfig>(["minResultChars", "minRunChars", "timeoutMs", "concurrency", "maxSegmentChars", "maxChunksPerSegment", "historyExchanges", "midRunMinAgeTurns", "midRunBatchChars", "midRunBatchCharsOpenAI", "smallResultMinChars", "keepRecentExchanges", "exchangeMinSavingChars"]);
+const INTEGER_KEYS = new Set<keyof GuardConfig>(["minResultChars", "minRunChars", "timeoutMs", "concurrency", "maxSegmentChars", "maxChunksPerSegment", "historyExchanges", "midRunMinAgeTurns", "midRunBatchChars", "midRunBatchCharsOpenAI", "smallResultMinChars", "keepRecentExchanges", "exchangeMinSavingChars", "imageKeepTurns"]);
 
 /** Merge untrusted JSON over the defaults, keeping only well-typed, in-range values. */
 export function normalizeConfig(raw: unknown): GuardConfig {

package/src/images.ts

@@ -0,0 +1,89 @@
+/**
+ * Old images (docs/DESIGN.md → Images). A model looks at a screenshot once: it describes or acts on it in
+ * its next message and goes on. Every later request still sends the image (about w×h/750 tokens each), so
+ * long runs with screenshots pile up context. Images in tool results are removed once they are
+ * `imageKeepTurns` turns old (assistant messages after the result). No Jev request is needed: Jev reads
+ * text only, and age is what decides. The result's text stays; a stub in front says what was removed, and
+ * `recall` returns the images. Images in user messages are always kept.
+ */
+import { MARKER, formatChars, toolLabel } from "./render.ts";
+import { indexSpan } from "./run.ts";
+import { contentChars, imageInfo } from "./size.ts";
+import { type Block, type MessageLike, type ProjectedEntryLike, textOf } from "./types.ts";
+
+export interface ImageItem {
+	/** Session entry id of the tool result. */
+	entryId: string;
+	toolName: string;
+	args?: Record<string, unknown>;
+	/** Position in the projection. */
+	index: number;
+	/** Assistant messages after the result. */
+	age: number;
+	images: number;
+	/** Estimated input tokens of the removed images. */
+	imageTokens: number;
+	/** Model-visible size before and after, in text characters (size.ts). */
+	beforeChars: number;
+	afterChars: number;
+	/** The new content: the stub, then the result's text blocks. */
+	replacement: { type: "text"; text: string }[];
+}
+
+const imageBlocks = (message: MessageLike | undefined): Block[] => (Array.isArray(message?.content) ? message.content.filter((b) => b.type === "image") : []);
+
+/** True for a tool result whose images were removed by us (the raw entry has images, the model sees none). */
+export const imagesRemoved = (projected: MessageLike | undefined, raw: MessageLike | undefined): boolean =>
+	projected?.role === "toolResult" && imageBlocks(raw).length > 0 && imageBlocks(projected).length === 0 && textOf(projected).startsWith(MARKER);
+
+export function imageStub(item: Pick<ImageItem, "entryId" | "images" | "imageTokens" | "age">, sizes: string[]): string {
+	const what = item.images === 1 ? "1 image" : `${item.images} images`;
+	const dims = sizes.length > 0 ? `${sizes.slice(0, 3).join(", ")}${sizes.length > 3 ? ", …" : ""}; ` : "";
+	const them = item.images === 1 ? "it" : "them";
+	return `${MARKER} Removed ${what} from this output (${dims}~${formatChars(item.imageTokens)} tokens), ${item.age} turns old. recall({"entryId":"${item.entryId}"}) shows ${them} again.`;
+}
+
+/**
+ * Tool results in `entries` (the whole projection, earlier runs included) with images that are at least
+ * `keepTurns` turns old. Skipped: results another extension changed (recall returns the raw entry, so
+ * their edit could not be restored) and results without images in the model's view.
+ */
+export function collectImages(entries: readonly ProjectedEntryLike[], keepTurns: number): ImageItem[] {
+	if (keepTurns <= 0) return [];
+	const { toolCalls } = indexSpan(entries);
+	// Assistant messages after each position.
+	const after = new Array<number>(entries.length + 1).fill(0);
+	for (let i = entries.length - 1; i >= 0; i--) after[i] = after[i + 1] + entries[i].messages.filter((m) => m.role === "assistant").length;
+	const items: ImageItem[] = [];
+	entries.forEach((entry, index) => {
+		const message = entry.messages[0];
+		if (entry.messages.length !== 1 || message?.role !== "toolResult" || !Array.isArray(message.content)) return;
+		const images = imageBlocks(message);
+		if (images.length === 0) return;
+		const age = after[index + 1];
+		if (age < keepTurns) return;
+		const raw = entry.sourceEntry.message;
+		if (raw && raw !== message && (textOf(raw) !== textOf(message) || imageBlocks(raw).length !== images.length)) return;
+		const call = message.toolCallId ? toolCalls.get(message.toolCallId) : undefined;
+		const infos = images.map(imageInfo);
+		const item = {
+			entryId: entry.sourceEntry.id,
+			toolName: message.toolName ?? call?.name ?? "tool",
+			...(call?.args ? { args: call.args } : {}),
+			index,
+			age,
+			images: images.length,
+			imageTokens: infos.reduce((n, i) => n + i.tokens, 0),
+		};
+		const sizes = infos.flatMap((i) => (i.width && i.height ? [`${i.width}×${i.height}`] : []));
+		const replacement = [
+			{ type: "text" as const, text: imageStub(item, sizes) },
+			...message.content.filter((b) => b.type === "text").map((b) => ({ type: "text" as const, text: b.text ?? "" })),
+		];
+		items.push({ ...item, beforeChars: contentChars(message.content), afterChars: contentChars(replacement), replacement });
+	});
+	return items;
+}
+
+export const imageLabel = (item: Pick<ImageItem, "toolName" | "args" | "images">): string =>
+	`${toolLabel({ toolName: item.toolName, args: item.args })} (${item.images === 1 ? "1 image" : `${item.images} images`})`;

package/src/index.ts

@@ -35,11 +35,12 @@ import {
 } from "./checkpoint.ts";
 import { buildCheckpointRequest } from "./decide.ts";
 import { type GuardConfig, loadConfig, parseModelRef, saveConfigPatch } from "./config.ts";
-import { omittedIdsFor, originalOutput, recallText } from "./recall.ts";
-import { formatChars, MARKER } from "./render.ts";
+import { collectImages, type ImageItem } from "./images.ts";
+import { omittedIdsFor, originalContent, RECALL_MAX_IMAGES, recallText } from "./recall.ts";
+import { formatChars, MARKER, RECALL_TOOL } from "./render.ts";
 import { collectExchanges, collectSmall, type ExchangeItem, type SmallItem, type WorkContext } from "./items.ts";
-import { deferExchanges, exchangeOmissions, type ProcessOptions, type ProcessOutcome, processItems } from "./process.ts";
-import { collectRun, findRunStart, type RunInfo } from "./run.ts";
+import { addImages, deferExchanges, dropImages, emptyOutcome, exchangeOmissions, type ProcessOptions, type ProcessOutcome, processItems } from "./process.ts";
+import { collectRun, findRunStart, lastUserIndex, type RunInfo } from "./run.ts";
 import {
 	CUSTOM_TYPE,
 	type Colorize,
@@ -154,8 +155,31 @@ export default function contextGuard(pi: ExtensionAPI) {
 	pi.on("session_compact", async (_event, ctx) => refreshStatus(ctx));
 	pi.on("agent_settled", async (_event, ctx) => refreshStatus(ctx));
 
-	/** Process every kind of item with the busy status shown; undefined when distillation could not start. */
+	/**
+	 * Process every kind of item with the busy status shown. Old images need no Jev request: with nothing
+	 * else to judge, or when Jev is unavailable, the outcome holds just them. Undefined when there is
+	 * nothing to do or distillation failed.
+	 */
 	const processWithStatus = async (
+		ctx: ExtensionContext,
+		run: RunInfo,
+		small: SmallItem[],
+		exchanges: ExchangeItem[],
+		images: ImageItem[],
+		work: WorkContext,
+		options: ProcessOptions,
+	): Promise<ProcessOutcome | undefined> => {
+		const withImages = (outcome: ProcessOutcome | undefined): ProcessOutcome | undefined => {
+			if (images.length === 0) return outcome;
+			const result = outcome ?? emptyOutcome();
+			addImages(result, images);
+			return result;
+		};
+		if (run.candidates.length === 0 && small.length === 0 && exchanges.length === 0) return withImages(undefined);
+		return withImages(await judgeWithStatus(ctx, run, small, exchanges, work, options));
+	};
+
+	const judgeWithStatus = async (
 		ctx: ExtensionContext,
 		run: RunInfo,
 		small: SmallItem[],
@@ -236,18 +260,25 @@ export default function contextGuard(pi: ExtensionAPI) {
 	 */
 	const exchangesPayOff = (ctx: ExtensionContext, entries: ProjectedEntryLike[], outcome: ProcessOutcome): boolean => {
 		const { savedChars, ids } = exchangeOmissions(outcome);
+		return earlyEditsPayOff(ctx, entries, outcome, ids, savedChars, config.exchangeMinSavingChars);
+	};
+
+	/** The same marginal-cost gate for edits `ids` that save `savedChars` (exchanges, images of earlier runs). */
+	const earlyEditsPayOff = (ctx: ExtensionContext, entries: ProjectedEntryLike[], outcome: ProcessOutcome, ids: ReadonlySet<string>, savedChars: number, minSavingChars: number): boolean => {
 		if (ids.size === 0) return true;
 		const others = new Set(outcome.edits.map((e) => e.targetId).filter((id) => !ids.has(id)));
 		const rewriteWith = rewriteCharsFor(ctx, entries, new Set([...others, ...ids]));
 		const rewriteWithout = others.size > 0 ? rewriteCharsFor(ctx, entries, others) : 0;
 		const marginal = rewriteWith - rewriteWithout;
 		if (marginal <= 0) return true;
-		if (savedChars < config.exchangeMinSavingChars) return false;
+		if (savedChars < minSavingChars) return false;
 		const requests = entries.filter((e) => e.messages[0]?.role === "assistant").length;
 		const factor = ctx.model?.provider === "openai-codex" ? BREAK_EVEN_FACTOR.full : BREAK_EVEN_FACTOR.prefix;
 		return paysOff(savedChars, requests, marginal, factor);
 	};
 
+	const imageSaving = (images: readonly ImageItem[]): number => images.reduce((n, i) => n + i.beforeChars - i.afterChars, 0);
+
 	pi.on("turn_end", async (event, ctx) => {
 		if (!config.enabled || !config.midRun || event.outcome !== "completed") return;
 		// The final turn of a run (no tool calls) is left to run-end distillation.
@@ -261,33 +292,43 @@ export default function contextGuard(pi: ExtensionAPI) {
 		const runStart = findRunStart(entries);
 		const small = config.smallResultMinChars > 0 ? collectSmall(entries.slice(runStart + 1), config, memo, info.currentTurn - config.midRunMinAgeTurns) : [];
 		let exchanges = config.pruneExchanges ? collectExchanges(entries, runStart, config.keepRecentExchanges, exchangeMemo(branch, CUSTOM_TYPE)) : [];
+		let images = collectImages(entries, config.imageKeepTurns);
 		const outputChars = info.pendingChars + small.reduce((n, item) => n + item.text.length, 0);
-		const exchangeChars = exchanges.reduce((n, item) => n + item.chars, 0);
-		if (outputChars + exchangeChars < batchCharsFor(ctx)) return;
-		// Only checkpoint when the one-time cache rewrite is likely to pay off (checkpoint.ts → paysOff).
-		// Old exchanges come early, so they move the rewrite start back; if the whole batch does not pay
-		// off, try the tool outputs alone.
-		if (config.midRunBreakEven) {
-			const factor = ctx.model?.provider === "openai-codex" ? BREAK_EVEN_FACTOR.full : BREAK_EVEN_FACTOR.prefix;
-			const outputIds = new Set([...info.candidates.map((c) => c.entryId), ...small.map((s) => s.entryId)]);
-			const allIds = new Set([...outputIds, ...exchanges.map((e) => e.entryId)]);
-			const turns = info.currentTurn + 1;
-			if (!paysOff(outputChars + exchangeChars, turns, rewriteCharsFor(ctx, entries, allIds), factor)) {
-				exchanges = [];
-				if (outputChars < batchCharsFor(ctx) || !paysOff(outputChars, turns, rewriteCharsFor(ctx, entries, outputIds), factor)) return;
-			}
-		}
+		// Only checkpoint when the batch is big enough and its one-time cache rewrite is likely to pay off
+		// (checkpoint.ts → paysOff). Old exchanges and images of earlier runs come early, so they move the
+		// rewrite start back: if the whole batch does not pay off, try without exchanges, then also without
+		// images from before the last user message.
+		const pin = lastUserIndex(entries);
+		const recentImages = images.filter((i) => i.index > pin);
+		const tiers = [
+			{ exchanges, images },
+			{ exchanges: [], images },
+			{ exchanges: [], images: recentImages },
+		];
+		const factor = ctx.model?.provider === "openai-codex" ? BREAK_EVEN_FACTOR.full : BREAK_EVEN_FACTOR.prefix;
+		const outputIds = [...info.candidates.map((c) => c.entryId), ...small.map((s) => s.entryId)];
+		const turns = info.currentTurn + 1;
+		const chosen = tiers.find((tier) => {
+			const chars = outputChars + imageSaving(tier.images) + tier.exchanges.reduce((n, item) => n + item.chars, 0);
+			if (chars < batchCharsFor(ctx)) return false;
+			if (!config.midRunBreakEven) return true;
+			const ids = new Set([...outputIds, ...tier.images.map((i) => i.entryId), ...tier.exchanges.map((e) => e.entryId)]);
+			return paysOff(chars, turns, rewriteCharsFor(ctx, entries, ids), factor);
+		});
+		if (!chosen) return;
+		exchanges = chosen.exchanges;
+		images = chosen.images;
 
 		const run: RunInfo = { question: info.question, answer: "", notes: info.notes, candidates: info.candidates, toolResults: 0, history: info.history };
 		const work: WorkContext = { question: info.question, history: info.history, latest: info.latest, notes: info.notes };
-		const outcome = await processWithStatus(ctx, run, small, exchanges, work, {
+		const outcome = await processWithStatus(ctx, run, small, exchanges, images, work, {
 			...config,
 			minRunChars: 0,
 			chunkKeepThreshold: config.midRunChunkKeepThreshold,
 			requestBuilder: (candidate, segment, segmentIndex, segmentCount, totalLines) =>
 				buildCheckpointRequest(info, candidate as CheckpointCandidate, segment, segmentIndex, segmentCount, totalLines),
 		});
-		if (!outcome || outcome.requests === 0) return;
+		if (!outcome || (outcome.requests === 0 && outcome.edits.length === 0)) return;
 
 		if (outcome.timedOut) warnOnce(ctx, "timeout", `Jev did not finish within ${config.timeoutMs} ms; some items were left as they are.`);
 		// The runner REPLACES the draft list with our return value: keep other extensions' drafts.
@@ -308,12 +349,19 @@ export default function contextGuard(pi: ExtensionAPI) {
 		const runStart = findRunStart(entries);
 		const small = config.smallResultMinChars > 0 ? collectSmall(entries.slice(runStart + 1), config, new Set()) : [];
 		const exchanges = config.pruneExchanges ? collectExchanges(entries, runStart, config.keepRecentExchanges, exchangeMemo(branchOf(ctx), CUSTOM_TYPE)) : [];
-		if (run.candidates.length === 0 && small.length === 0 && exchanges.length === 0) return;
+		const images = collectImages(entries, config.imageKeepTurns);
+		if (run.candidates.length === 0 && small.length === 0 && exchanges.length === 0 && images.length === 0) return;
 		const work: WorkContext = { question: run.question, history: run.history ?? { exchanges: [] }, answer: run.answer };
 
-		const outcome = await processWithStatus(ctx, run, small, exchanges, work, config);
-		if (!outcome || outcome.requests === 0) return;
+		const outcome = await processWithStatus(ctx, run, small, exchanges, images, work, config);
+		if (!outcome || (outcome.requests === 0 && outcome.edits.length === 0)) return;
 		if (config.exchangeBreakEven && !exchangesPayOff(ctx, entries, outcome)) deferExchanges(outcome);
+		// Images of earlier runs (before this run's prompt) move the cache rewrite back like exchanges do.
+		const early = images.filter((i) => i.index < runStart);
+		if (config.exchangeBreakEven && !earlyEditsPayOff(ctx, entries, outcome, new Set(early.map((i) => i.entryId)), imageSaving(early), 0)) {
+			dropImages(outcome, new Set(early.map((i) => i.entryId)));
+		}
+		if (outcome.requests === 0 && outcome.edits.length === 0) return;
 		if (outcome.timedOut) warnOnce(ctx, "timeout", `Jev did not finish within ${config.timeoutMs} ms; some items were left as they are.`);
 		// The runner REPLACES the draft list with our return value: keep other extensions' drafts.
 		return { entries: [...event.entries, ...(outcome.edits as never[]), recordOf(outcome, "run-end")] };
@@ -353,11 +401,11 @@ export default function contextGuard(pi: ExtensionAPI) {
 	});
 
 	pi.registerTool({
-		name: "recall",
+		name: RECALL_TOOL,
 		label: "Recall",
 		description:
 			`Return the original of something context-guard distilled or omitted (its text starts with "${MARKER}"): a tool output, ` +
-			"or a whole earlier exchange (prompt, replies, tool calls and results). Pass the entryId from that note. Optionally pass a regex `pattern` to get only matching lines (with line numbers), " +
+			"or a whole earlier exchange (prompt, replies, tool calls and results), or images removed from an output (they come back as images). Pass the entryId from that note. Optionally pass a regex `pattern` to get only matching lines (with line numbers), " +
 			"and `offset`/`limit` (1-based) to page through a long output; with a `pattern` they count matching lines.",
 		promptSnippet: `recall: fetch the full original of a tool output or earlier exchange marked "${MARKER}"`,
 		parameters: Type.Object({
@@ -368,9 +416,13 @@ export default function contextGuard(pi: ExtensionAPI) {
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const branch = ctx.sessionManager.getBranch() as never;
-			const original = originalOutput(ctx.sessionManager.getEntry(params.entryId) as never, params.entryId, branch, omittedIdsFor(branch, params.entryId, CUSTOM_TYPE));
-			const text = recallText(original, params);
-			return { content: [{ type: "text", text }], details: undefined };
+			const original = originalContent(ctx.sessionManager.getEntry(params.entryId) as never, params.entryId, branch, omittedIdsFor(branch, params.entryId, CUSTOM_TYPE));
+			const text = recallText(original.text, params);
+			// Images come with the first page of a plain recall, not with a pattern search.
+			const withImages = !params.pattern && !(params.offset && params.offset > 1);
+			const images = withImages ? original.images.slice(0, RECALL_MAX_IMAGES) : [];
+			const note = original.images.length > images.length ? `\n[${original.images.length} image(s) in the original${images.length > 0 ? `, ${images.length} attached` : ""}${withImages ? "" : "; recall without pattern/offset to see them"}]` : "";
+			return { content: [{ type: "text", text: text + note }, ...(images as never[])], details: undefined };
 		},
 	});
 
@@ -399,13 +451,14 @@ export default function contextGuard(pi: ExtensionAPI) {
 function describe(config: GuardConfig, stats: GuardStats, problem: string | undefined): string {
 	const lines = [
 		`context-guard is ${config.enabled ? "on" : "off"}${problem && config.enabled ? ` (${problem})` : ""} · model ${config.model}`,
-		`Saving ~${formatTokens(stats.savedTokens)} tokens (${formatChars(stats.savedChars)} chars): ${stats.distilledResults} distilled tool output(s), ${stats.omittedExchanges} omitted exchange(s).`,
+		`Saving ~${formatTokens(stats.savedTokens)} tokens (${formatChars(stats.savedChars)} chars): ${stats.distilledResults} distilled tool output(s), ${stats.imageResults} output(s) without their images, ${stats.omittedExchanges} omitted exchange(s).`,
+		...(stats.compacted ? [`Σ ~${formatTokens(stats.lifetimeTokens)} tokens saved on this branch in total; a compaction has since dropped the earlier edits from context.`] : []),
 		`Jev: ${stats.runs - stats.checkpoints} run(s) and ${stats.checkpoints} mid-run checkpoint(s), ${stats.requests} request(s), ${formatCost(stats.costUsd)} on this branch.`,
-		`Mid-run checkpoints are ${config.midRun ? `on (outputs ≥ ${config.midRunMinAgeTurns} turns old, batches of ≥ ${formatChars(config.midRunBatchChars)} chars)` : "off"}; old exchanges are ${config.pruneExchanges ? `judged (all but the last ${config.keepRecentExchanges})` : "kept"}.`,
+		`Mid-run checkpoints are ${config.midRun ? `on (outputs ≥ ${config.midRunMinAgeTurns} turns old, batches of ≥ ${formatChars(config.midRunBatchChars)} chars)` : "off"}; old exchanges are ${config.pruneExchanges ? `judged (all but the last ${config.keepRecentExchanges})` : "kept"}; tool-output images are ${config.imageKeepTurns > 0 ? `removed after ${config.imageKeepTurns} turns` : "kept"}.`,
 	];
 	const last = stats.last;
 	if (last) {
-		const kinds = ["large", "small", "exchange"].map((kind) => `${last.results.filter((r) => (r.kind ?? "large") === kind).length} ${kind}`).join(", ");
+		const kinds = ["large", "small", "exchange", "image"].map((kind) => `${last.results.filter((r) => (r.kind ?? "large") === kind).length} ${kind}`).join(", ");
 		lines.push(`Last ${last.phase === "mid-run" ? "checkpoint" : "run"} (${(last.ms / 1000).toFixed(1)} s${last.timedOut ? ", timed out" : ""}; ${kinds}):`);
 		for (const result of last.results) {
 			const sizes = result.outcome === "kept" ? formatChars(result.beforeChars) : `${formatChars(result.beforeChars)} → ${formatChars(result.afterChars)}`;

package/src/items.ts

@@ -4,9 +4,10 @@
  * output becomes a one-line stub; an omitted exchange keeps a stub on its user prompt and omits every
  * other entry (`replacement: null`).
  */
-import { MARKER, formatChars, toolLabel } from "./render.ts";
+import { MARKER, RECALL_TOOL, formatChars, toolLabel } from "./render.ts";
 import { supersededBy } from "./checkpoint.ts";
-import { type Candidate, type CollectOptions, candidateOf, indexSpan, type RunHistory } from "./run.ts";
+import { contentChars } from "./size.ts";
+import { type Candidate, type CollectOptions, candidateOf, indexSpan, isSteering, type RunHistory } from "./run.ts";
 import {
 	type ClassifierQuestion,
 	type ClassifierRequest,
@@ -18,7 +19,7 @@ import {
 	textOf,
 } from "./types.ts";
 
-export type ItemKind = "large" | "small" | "exchange";
+export type ItemKind = "large" | "small" | "exchange" | "image";
 
 // ---------------------------------------------------------------------------------------------
 // Small outputs
@@ -38,7 +39,8 @@ export interface SmallOptions extends CollectOptions {
 /**
  * Tool results of the run span `span` (entries after the run's user message) between
  * `smallResultMinChars` and `minResultChars`, under the same candidate rules as large outputs. With
- * `youngest`, only outputs whose call was made in a turn ≤ youngest (the mid-run age rule).
+ * `youngest`, only outputs whose call was made in a turn ≤ youngest (the mid-run age rule), and no
+ * recall outputs.
  */
 export function collectSmall(span: readonly ProjectedEntryLike[], options: SmallOptions, judged: ReadonlySet<string>, youngest = Number.POSITIVE_INFINITY): SmallItem[] {
 	const { toolCalls } = indexSpan(span);
@@ -49,6 +51,8 @@ export function collectSmall(span: readonly ProjectedEntryLike[], options: Small
 		if (!candidate || candidate.text.length >= options.minResultChars || judged.has(candidate.entryId)) continue;
 		const turn = candidate.turn ?? 0;
 		if (turn > youngest) continue;
+		// Mid-run (`youngest` given): recall outputs are left alone, see checkpoint.ts → collectCheckpoint.
+		if (Number.isFinite(youngest) && candidate.toolName === RECALL_TOOL) continue;
 		const { toolCallId: _id, turn: _turn, ...plain } = candidate;
 		// Skip outputs whose stub would not be shorter.
 		if (smallStub(plain).length >= plain.text.length) continue;
@@ -91,17 +95,11 @@ const isEditable = (entry: ProjectedEntryLike): boolean => {
 	return role === "user" || role === "assistant" || role === "toolResult";
 };
 
-const entryChars = (entry: ProjectedEntryLike): number =>
-	entry.messages.reduce((n, m) => n + (typeof m.content === "string" ? m.content.length : JSON.stringify(m.content ?? "").length), 0);
+const entryChars = (entry: ProjectedEntryLike): number => entry.messages.reduce((n, m) => n + contentChars(m.content), 0);
 
 /** Exchanges smaller than this (model-visible characters) are never judged: the saving is not worth an edit. */
 export const EXCHANGE_MIN_CHARS = 2_000;
 
-const hasImage = (entry: ProjectedEntryLike): boolean =>
-	[...entry.messages, ...(entry.sourceEntry.message ? [entry.sourceEntry.message] : [])].some(
-		(m) => Array.isArray(m.content) && m.content.some((b) => b.type === "image"),
-	);
-
 /**
  * True when the model sees something other than the raw entry and the difference is not ours: another
  * extension (or Pi's overflow recovery) replaced or omitted it. `recall` returns raw entries, so whatever
@@ -126,7 +124,8 @@ const editedByOthers = (entry: ProjectedEntryLike): boolean => {
  */
 export function collectExchanges(entries: readonly ProjectedEntryLike[], runStart: number, keepRecent: number, judged: ReadonlySet<string>): ExchangeItem[] {
 	const starts: number[] = [];
-	for (let i = 0; i < runStart; i++) if (entries[i].messages.some((m) => m.role === "user")) starts.push(i);
+	// Steering messages belong to the exchange they were sent in.
+	for (let i = 0; i < runStart; i++) if (entries[i].messages.some((m) => m.role === "user") && !isSteering(entries, i)) starts.push(i);
 	const exchanges: ExchangeItem[] = [];
 	starts.slice(0, Math.max(0, starts.length - keepRecent)).forEach((start, k) => {
 		const end = k + 1 < starts.length ? starts[k + 1] : runStart;
@@ -135,8 +134,8 @@ export function collectExchanges(entries: readonly ProjectedEntryLike[], runStar
 		if (!isEditable(user) || judged.has(user.sourceEntry.id)) return;
 		const promptText = textOf(user.messages[0]);
 		if (promptText.startsWith(MARKER)) return; // already omitted
-		// Recoverability: recall returns raw entries as text, so no images and no foreign edits.
-		if (span.some((e) => hasImage(e) || editedByOthers(e))) return;
+		// Recoverability: recall returns raw entries (with their images, see recall.ts), so no foreign edits.
+		if (span.some(editedByOthers)) return;
 		const assistants = span.filter((e) => e.messages[0]?.role === "assistant");
 		const lastAssistant = assistants.at(-1)?.messages[0];
 		if (!lastAssistant || (Array.isArray(lastAssistant.content) && lastAssistant.content.some((b) => b.type === "toolCall"))) return;

package/src/process.ts

@@ -20,6 +20,7 @@ import {
 	smallStub,
 	type WorkContext,
 } from "./items.ts";
+import { type ImageItem, imageLabel } from "./images.ts";
 import { toolLabel } from "./render.ts";
 import type { RunInfo } from "./run.ts";
 import type { ClassifyFn, ContextEditDraft, OmitDraft } from "./types.ts";
@@ -143,6 +144,42 @@ export async function processItems(
 
 
 
+export const emptyOutcome = (): ProcessOutcome => ({ edits: [], records: [], savedChars: 0, requests: 0, inputTokens: 0, costUsd: 0, ms: 0, timedOut: false });
+
+/** Add the removal of old images (no Jev request; images.ts) to `outcome`. */
+export function addImages(outcome: ProcessOutcome, items: readonly ImageItem[]): void {
+	for (const item of items) {
+		outcome.edits.push({ type: "context_edit", targetId: item.entryId, replacement: { content: item.replacement } });
+		outcome.records.push({
+			kind: "image",
+			entryId: item.entryId,
+			tool: item.toolName,
+			label: imageLabel(item),
+			outcome: "removed",
+			reason: `${item.age} turns old`,
+			beforeChars: item.beforeChars,
+			afterChars: item.afterChars,
+			keptLines: 0,
+			totalLines: 0,
+			chunks: 1,
+			requests: 0,
+			jev: [],
+		});
+		outcome.savedChars += item.beforeChars - item.afterChars;
+	}
+}
+
+/** Take image removals for `ids` back out of `outcome` (they stay eligible for a later pass). */
+export function dropImages(outcome: ProcessOutcome, ids: ReadonlySet<string>): void {
+	if (ids.size === 0) return;
+	outcome.edits = outcome.edits.filter((e) => !ids.has(e.targetId));
+	outcome.records = outcome.records.filter((r) => {
+		if (r.kind !== "image" || !ids.has(r.entryId)) return true;
+		outcome.savedChars -= r.beforeChars - r.afterChars;
+		return false;
+	});
+}
+
 /** Net characters the outcome's exchange omissions remove, and the entry ids they edit. */
 export function exchangeOmissions(outcome: ProcessOutcome): { savedChars: number; ids: Set<string> } {
 	const ids = new Set<string>();