pi-context-guard-jev 0.1.0 → 0.3.1

package/src/config.ts

@@ -46,8 +46,45 @@ export interface GuardConfig {
 	 * against the ongoing work too. 0 sends no earlier conversation at all (no summary either).
 	 */
 	historyExchanges: number;
-	/** Add an Anthropic cache breakpoint at the previous user question (see docs/CACHE.md). */
+	/**
+	 * Add Anthropic cache breakpoints: at the previous user question, and after context edits at a
+	 * read point before the first edited output (see docs/CACHE.md).
+	 */
 	pinAnthropicCache: boolean;
+	/** Mid-run checkpoints: judge older tool outputs while a long run is still going. */
+	midRun: boolean;
+	/** A tool output is judged mid-run only once its turn is at least this many turns old. */
+	midRunMinAgeTurns: number;
+	/** Run a checkpoint only when the not-yet-judged eligible outputs total at least this (characters). */
+	midRunBatchChars: number;
+	/** Batch size for OpenAI Codex models, whose first request after an edit reads (almost) nothing from cache. */
+	midRunBatchCharsOpenAI: number;
+	/** Keep a chunk at a checkpoint when P(still needed) reaches this. */
+	midRunChunkKeepThreshold: number;
+	/** Skip a checkpoint unless its one-time prompt-cache rewrite is likely to pay off (docs/CACHE.md). */
+	midRunBreakEven: boolean;
+	/** Tool results from this size up to `minResultChars` are judged as whole items (0 turns this off). */
+	smallResultMinChars: number;
+	/** Keep a small output when P(still needed) reaches this. */
+	smallKeepThreshold: number;
+	/** Omit old exchanges judged unrelated to the current work. */
+	pruneExchanges: boolean;
+	/** The last this many exchanges before the current prompt are never omitted. */
+	keepRecentExchanges: number;
+	/** Omit an exchange only when P(still relevant) is below this. */
+	exchangeOmitThreshold: number;
+	/**
+	 * Gate exchange omission at run end by the break-even rule (and `exchangeMinSavingChars`); deferred
+	 * exchanges stay eligible and accumulate. `false` always omits unrelated exchanges.
+	 */
+	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 = {
@@ -69,6 +106,20 @@ export const DEFAULT_CONFIG: GuardConfig = {
 	distillErrors: true,
 	historyExchanges: 3,
 	pinAnthropicCache: true,
+	midRun: true,
+	midRunMinAgeTurns: 4,
+	midRunBatchChars: 60_000,
+	midRunBatchCharsOpenAI: 60_000,
+	midRunChunkKeepThreshold: 0.6,
+	midRunBreakEven: true,
+	smallResultMinChars: 400,
+	smallKeepThreshold: 0.45,
+	pruneExchanges: true,
+	keepRecentExchanges: 2,
+	exchangeOmitThreshold: 0.2,
+	exchangeBreakEven: true,
+	exchangeMinSavingChars: 8_000,
+	imageKeepTurns: 3,
 };
 
 const NUMBER_RANGES: Partial<Record<keyof GuardConfig, [number, number]>> = {
@@ -84,9 +135,19 @@ const NUMBER_RANGES: Partial<Record<keyof GuardConfig, [number, number]>> = {
 	maxSegmentChars: [2_000, 200_000],
 	maxChunksPerSegment: [2, 60],
 	historyExchanges: [0, 10],
+	midRunMinAgeTurns: [1, 100],
+	midRunBatchChars: [0, 10_000_000],
+	midRunBatchCharsOpenAI: [0, 10_000_000],
+	midRunChunkKeepThreshold: [0, 1],
+	smallResultMinChars: [0, 10_000_000],
+	smallKeepThreshold: [0, 1],
+	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"]);
+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/decide.ts

@@ -11,6 +11,8 @@
  * can only name the most important chunk; the per-chunk yes/no questions add the others.
  */
 import type { Chunk } from "./chunk.ts";
+import type { CheckpointCandidate, CheckpointInfo } from "./checkpoint.ts";
+import { recentNotes } from "./checkpoint.ts";
 import { type Candidate, hasHistory, type RunHistory, type RunInfo } from "./run.ts";
 import { type ClassifierQuestion, type ClassifierRequest, type ClassifierResponse, clip } from "./types.ts";
 
@@ -121,6 +123,78 @@ export function buildRequest(
 	return { state, questions };
 }
 
+const PROGRESS_LIMIT = 2_000;
+
+/**
+ * Request for a mid-run checkpoint: there is no final answer yet, so Jev judges whether the agent
+ * will still need the output to finish the task (docs/JEV.md → Checkpoint wording). The run-end
+ * wording in `buildRequest` is untouched.
+ */
+export function buildCheckpointRequest(
+	info: Pick<CheckpointInfo, "question" | "history" | "latest" | "notes">,
+	candidate: CheckpointCandidate,
+	segment: readonly Chunk[],
+	segmentIndex: number,
+	segmentCount: number,
+	totalLines: number,
+): ClassifierRequest {
+	const withHistory = hasHistory(info.history);
+	const state: Record<string, unknown> = {
+		situation:
+			"A coding agent is still working on user_question; it has not finished yet. This is the output of one of its earlier tool " +
+			"calls, split into chunks. From now on the agent will only see the chunks we keep, plus a note that the rest was removed " +
+			"and can be fetched again. later_tool_calls shows what the agent did after this call." +
+			(withHistory ? " earlier_conversation shows the session before this task." : ""),
+	};
+	if (withHistory) state.earlier_conversation = describeHistory(info.history);
+	state.user_question = clip(info.question, QUESTION_LIMIT);
+	const progress: Record<string, string> = {};
+	if (info.latest.trim()) progress.latest_note = clip(info.latest, PROGRESS_LIMIT);
+	if (info.notes.trim()) progress.earlier_notes = recentNotes(info.notes, PROGRESS_LIMIT);
+	if (Object.keys(progress).length > 0) state.agent_progress = progress;
+	state.later_tool_calls = candidate.laterCalls.length > 0 ? candidate.laterCalls : "none yet";
+	if (candidate.superseded) state.superseded = candidate.superseded;
+	state.tool = candidate.toolName;
+	if (candidate.isError) state.tool_status = "failed (the tool reported an error, e.g. a non-zero exit code).";
+	const args = describeArgs(candidate.args);
+	if (args) state.tool_arguments = args;
+	state.output_size = `${totalLines} lines${segmentCount > 1 ? `; this is part ${segmentIndex + 1} of ${segmentCount}` : ""}`;
+	state.chunks = Object.fromEntries(segment.map((chunk) => [chunkLabel(chunk), chunk.text]));
+
+	const scope = segmentCount > 1 ? "this part of the tool output" : "the tool output";
+	const focusCriteria: Record<string, string> = {
+		whole: `Most of ${scope} will still be needed`,
+		none: `Nothing in ${scope} will be needed again`,
+	};
+	for (const chunk of segment) {
+		const label = chunkLabel(chunk);
+		focusCriteria[label] = `A few chunks will still be needed; ${label} is the most important of them`;
+	}
+	const questions: Record<string, ClassifierQuestion> = {
+		keep_whole: {
+			type: "bool",
+			instructions: `To finish user_question, will the agent still need all of ${scope}, so that removing any chunk would lose information it is likely to use again?`,
+			criteria: { true: "Keep everything", false: "Some chunks will not be needed again and can be removed" },
+		},
+		focus: {
+			type: "choice",
+			instructions:
+				`Will the rest of the agent's work draw on most of ${scope}, or on a few chunks? If a few, pick the most important chunk. ` +
+				"If nothing in it will be needed again (for example because it is out of date or the agent has moved past it), pick none.",
+			criteria: focusCriteria,
+		},
+	};
+	for (const chunk of segment) {
+		const label = chunkLabel(chunk);
+		questions[label] = {
+			type: "bool",
+			instructions: `To finish user_question, will the agent still need the lines in ${label}? Lines that are out of date or that the agent has already acted on and moved past are not needed.`,
+			criteria: { true: `Keep ${label}`, false: `${label} will not be needed again` },
+		};
+	}
+	return { state, questions };
+}
+
 /** Basenames and paths mentioned in the answer, for the citation safety net. */
 export function citedFiles(answer: string, chunks: readonly Chunk[]): Set<number> {
 	const keep = new Set<number>();

package/src/distill.ts

@@ -8,7 +8,10 @@ import { type Chunk, chunkOutput, DEFAULT_CHUNK_OPTIONS, segmentChunks } from ".
 import { buildRequest, citedFiles, type DecideThresholds, interpret, type SegmentDecision } from "./decide.ts";
 import { renderReplacement, toolLabel } from "./render.ts";
 import type { Candidate, RunInfo } from "./run.ts";
-import type { ClassifierResponse, ClassifyFn, ContextEditDraft } from "./types.ts";
+import type { ClassifierRequest, ClassifierResponse, ClassifyFn, ContextEditDraft } from "./types.ts";
+
+/** Builds the Jev request for one segment; defaults to the run-end request (`buildRequest`). */
+export type RequestBuilder = (candidate: Candidate, segment: readonly Chunk[], segmentIndex: number, segmentCount: number, totalLines: number) => ClassifierRequest;
 
 export interface DistillOptions extends DecideThresholds {
 	minRunChars: number;
@@ -18,6 +21,8 @@ export interface DistillOptions extends DecideThresholds {
 	concurrency: number;
 	maxSegmentChars: number;
 	maxChunksPerSegment: number;
+	/** Mid-run checkpoints pass their own request builder. */
+	requestBuilder?: RequestBuilder;
 }
 
 export type ResultOutcome = "distilled" | "removed" | "kept";
@@ -128,7 +133,9 @@ export async function distillRun(
 	try {
 		await pool(tasks.filter((task) => !task.decision), options.concurrency, signal, async (task) => {
 			const candidate = run.candidates[task.candidate];
-			const request = buildRequest(run, candidate, task.segment, task.segmentIndex, task.segmentCount, task.totalLines);
+			const request = options.requestBuilder
+				? options.requestBuilder(candidate, task.segment, task.segmentIndex, task.segmentCount, task.totalLines)
+				: buildRequest(run, candidate, task.segment, task.segmentIndex, task.segmentCount, task.totalLines);
 			outcome.requests++;
 			try {
 				// Race the request against the budget: a provider that ignores the signal must not

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`})`;