pi-jev-lens 0.1.0

package/src/classifier.ts

@@ -0,0 +1,151 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { Config } from "./config.ts";
+import type { Probabilities } from "./types.ts";
+import { head, tail, truncate } from "./text.ts";
+
+/** Everything jev sees about one tool result. Built identically by the extension and the replay harness. */
+export interface ItemState {
+	task: { first_user_request: string; latest_user_message: string };
+	item: {
+		tool: string;
+		args: string;
+		is_error: boolean;
+		total_chars: number;
+		output_head: string;
+		output_tail: string;
+	};
+	after: {
+		assistant_text: string;
+		next_tool_calls: { name: string; args: string }[];
+	};
+}
+
+export interface TextState {
+	task: { first_user_request: string };
+	message: string;
+	role: "user" | "agent";
+}
+
+export interface Classifier {
+	classifyToolResult(state: ItemState, signal?: AbortSignal): Promise<Probabilities>;
+	classifyText(state: TextState, signal?: AbortSignal): Promise<number>;
+}
+
+export function buildItemState(
+	cfg: Pick<Config, "stateHeadChars" | "stateTailChars">,
+	input: {
+		firstUser: string;
+		latestUser: string;
+		toolName: string;
+		args: unknown;
+		isError: boolean;
+		output: string;
+		afterText: string;
+		afterCalls: { name: string; arguments: unknown }[];
+	},
+): ItemState {
+	return {
+		task: {
+			first_user_request: truncate(input.firstUser, 600),
+			latest_user_message: truncate(input.latestUser, 400),
+		},
+		item: {
+			tool: input.toolName,
+			args: truncate(JSON.stringify(input.args ?? {}), 300),
+			is_error: input.isError,
+			total_chars: input.output.length,
+			output_head: head(input.output, cfg.stateHeadChars),
+			output_tail: input.output.length > cfg.stateHeadChars ? tail(input.output, cfg.stateTailChars) : "",
+		},
+		after: {
+			assistant_text: truncate(input.afterText, 800),
+			next_tool_calls: input.afterCalls.slice(0, 8).map((c) => ({ name: c.name, args: truncate(JSON.stringify(c.arguments ?? {}), 150) })),
+		},
+	};
+}
+
+export const TOOL_RESULT_QUESTIONS = {
+	needed: {
+		type: "noul" as const,
+		instructions:
+			"`item` is the output of a tool the coding agent ran while working on `task`. `after` shows what the agent said and which tools it called right after seeing this output. Will the agent still need the full text of `item.output_head` and `item.output_tail` verbatim in its upcoming steps?",
+		criteria: {
+			true: "The agent is still working on what this output shows: it will edit, quote, compare against, or reason over specific lines of it; or it has not acted on it yet; or the output holds details (line numbers, exact error text, exact code) it will need again.",
+			false: "The agent already acted on it (edited the file, fixed the error, answered from it), moved on to a different area, the output was a dead end or irrelevant, or it is cheap to regenerate by running the same tool again.",
+		},
+	},
+	outcome_only: {
+		type: "noul" as const,
+		instructions:
+			"Is the useful information in `item` limited to its outcome, such as success or failure, the final status lines, an error message, or a count, so that the middle of the output could be dropped without losing anything the agent needs?",
+		criteria: {
+			true: "Command output, logs, install or build noise, test runs where only the pass/fail summary or the failing case matters.",
+			false: "Source code, file contents, search results, directory listings, or any output where specific lines in the middle carry the information.",
+		},
+	},
+	durable: {
+		type: "noul" as const,
+		instructions:
+			"Does `item` reveal a stable fact about this project (its structure, conventions, how to build, test or run it, a known pitfall) or about the user's preferences, that would still be true and useful in a future, unrelated session?",
+		criteria: {
+			true: "Build or test commands that work, project layout, conventions, configuration quirks, recurring gotchas.",
+			false: "Task-specific content, transient state, one-off command output, file contents that change with every edit.",
+		},
+	},
+};
+
+export const TEXT_QUESTIONS = {
+	durable_user: {
+		type: "noul" as const,
+		instructions:
+			"`message` was written by the user to a coding agent. Does it state a preference, standing instruction, or fact about the user or the project that should be remembered in future sessions, rather than a one-off task instruction?",
+		criteria: {
+			true: "Coding style preferences, tools or workflows the user wants used, facts about the project's purpose, constraints that will keep applying.",
+			false: "A task for right now, a question, feedback about one specific change, small talk.",
+		},
+	},
+	durable_agent: {
+		type: "noul" as const,
+		instructions:
+			"`message` was written by a coding agent. Does it state a conclusion, decision, or discovered fact about the project that will remain true and be useful in future unrelated sessions?",
+		criteria: {
+			true: "How the project is structured, where things live, what command runs the tests, a root cause that explains recurring behaviour, a design decision that was made.",
+			false: "Progress narration, a plan for the current task, a question to the user, a summary of edits just made.",
+		},
+	},
+};
+
+export class JevClassifier implements Classifier {
+	private client: TypeSafeClient;
+	private model: string;
+	constructor(cfg: Pick<Config, "apiKey" | "model">) {
+		this.client = new TypeSafeClient({ apiKey: cfg.apiKey });
+		this.model = cfg.model;
+	}
+	async classifyToolResult(state: ItemState, signal?: AbortSignal): Promise<Probabilities> {
+		const r = await this.client.systemOne({ state: state as never, questions: TOOL_RESULT_QUESTIONS, model: this.model }, { signal, timeout: 15000 });
+		return { needed: r.answers.needed.noul, outcomeOnly: r.answers.outcome_only.noul, durable: r.answers.durable.noul };
+	}
+	async classifyText(state: TextState, signal?: AbortSignal): Promise<number> {
+		const q = state.role === "user" ? { durable: TEXT_QUESTIONS.durable_user } : { durable: TEXT_QUESTIONS.durable_agent };
+		const r = await this.client.systemOne({ state: { task: state.task, message: state.message }, questions: q, model: this.model }, { signal, timeout: 15000 });
+		return r.answers.durable.noul;
+	}
+}
+
+/** Deterministic stand-in for tests and dry runs. Never touches the network. */
+export class MockClassifier implements Classifier {
+	constructor(private rule: (state: ItemState) => Probabilities = defaultMockRule) {}
+	async classifyToolResult(state: ItemState): Promise<Probabilities> {
+		return this.rule(state);
+	}
+	async classifyText(): Promise<number> {
+		return 0;
+	}
+}
+
+export function defaultMockRule(state: ItemState): Probabilities {
+	const big = state.item.total_chars > 2000;
+	const cmd = state.item.tool === "bash";
+	return { needed: big ? 0.1 : 0.9, outcomeOnly: cmd ? 0.9 : 0.1, durable: 0 };
+}

package/src/config.ts

@@ -0,0 +1,188 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type SealMode = "rolling" | "batch" | "budget";
+
+export interface Config {
+	/** Disable all pruning (classification still runs and logs). */
+	enabled: boolean;
+	/**
+	 * rolling: apply decisions at the next LLM call (smallest prompt, one cache rewrite per call while pruning).
+	 * batch: apply only when the cache is cold or on compaction (best cache, prompt shrinks late).
+	 * budget: like batch, but also apply when pending prunable tokens exceed a share of the prompt (one rewrite buys many calls).
+	 */
+	mode: SealMode;
+	/** budget mode: apply pending decisions when they remove at least this fraction of the tail they would rewrite... */
+	budgetFraction: number;
+	/** ...and at least this many tokens. */
+	budgetMinTokens: number;
+	/** P(needed) below this → forget (stub). */
+	forgetBelow: number;
+	/** P(needed) below this and P(outcomeOnly) above trimAbove → trim to head+tail. */
+	trimBelow: number;
+	trimAbove: number;
+	/** P(durable) above this → written to the memory file. */
+	durableAbove: number;
+	/** Tool results smaller than this (estimated tokens) are never touched. */
+	minTokens: number;
+	/** Maximum wait for in-flight classifications at context, agent end and shutdown. */
+	classifyWaitMs: number;
+	/** Provider prompt-cache TTL; idle longer than this means the cache is cold. */
+	cacheTtlMs: number;
+	/** Lines kept at head/tail when trimming. */
+	trimHeadLines: number;
+	trimTailLines: number;
+	/** Max chars of tool output sent to jev (head + tail). */
+	stateHeadChars: number;
+	stateTailChars: number;
+	/** Pre-send compression of large tool results (jev picks a view before the output is ever sent). */
+	presend: boolean;
+	/** Only results at least this large (estimated tokens) are considered for pre-send compression. */
+	presendMinTokens: number;
+	/** Send full when P(needs full) is above this. */
+	presendNeedsFullAbove: number;
+	/** Send full when the "full" option itself gets more than this probability mass. */
+	presendFullMassAbove: number;
+	/** Separate needs-full threshold for command output (test runs), where "exact full text" is rarely what the agent needs. */
+	presendCommandNeedsFullAbove: number;
+	/** Code policy: "gate" (default) = jev's needs-full/full-mass gates decide between full and a view; "outline" = code is always sent as outline plus the blocks the second step expands (17 % edit-miss on 500 real trajectories, see STATUS). */
+	presendCodePolicy: "gate" | "outline";
+	/** Stricter needs-full threshold for source code, where a wrong view costs an edit (jev's answers vary run to run by ±0.2). */
+	presendCodeNeedsFullAbove: number;
+	/** Send full when the choice confidence is below this (0 = off; a spread over acceptable views is not a reason to send everything). */
+	presendMinConfidence: number;
+	/** Second step for code: expand the bodies of blocks jev says the agent will need (P above this). */
+	presendExpandAbove: number;
+	/** Command policy: "sections" (default) = when jev picks full for command output but needs-full is under the command threshold, send section headers and let the second step expand the sections it needs; "gate" = jev's view choice stands. */
+	presendCommandPolicy: "gate" | "sections";
+	/** Second step for command output: expand a section when P(needed) is above this. */
+	presendSectionExpandAbove: number;
+	/** Command output: when no section reaches this probability the step is uninformative and full is sent (0 = headers alone are allowed). */
+	presendSectionFloor: number;
+	model: string;
+	/** Optional variant file (JEV_LENS_VARIANT): { config, prompts, views } overrides, as produced by eval/bench/autoresearch.ts. */
+	variantFile: string | undefined;
+	/** Force the mock classifier even when a key is present (tests, dry runs). */
+	forceMock: boolean;
+	logFile: boolean;
+	apiKey: string | undefined;
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Where `/jev-lens key` stores the TypeSafe API key (overridable for tests). */
+export function keyFilePath(): string {
+	return process.env.JEV_LENS_KEY_FILE || join(homedir(), ".pi", "agent", "jev-lens.json");
+}
+
+/** The stored key, if any. */
+export function readStoredKey(): string | undefined {
+	try {
+		const p = keyFilePath();
+		if (!existsSync(p)) return undefined;
+		const key = (JSON.parse(readFileSync(p, "utf8")) as { apiKey?: unknown }).apiKey;
+		return typeof key === "string" && key.trim() ? key.trim() : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Store the key in the user's pi directory, readable only by the user. */
+export function storeKey(key: string): string {
+	const p = keyFilePath();
+	mkdirSync(dirname(p), { recursive: true });
+	writeFileSync(p, `${JSON.stringify({ apiKey: key.trim() }, null, 2)}\n`, { mode: 0o600 });
+	return p;
+}
+
+/** Key resolution: environment (or the package's .env, loaded into it), then the stored key. */
+export function resolveApiKey(): string | undefined {
+	return process.env.TYPESAFE_API_KEY || readStoredKey();
+}
+
+/** Load KEY=VALUE lines from the extension's own .env (never from the target project). */
+export function loadDotEnv(): void {
+	for (const dir of [join(HERE, ".."), HERE]) {
+		const p = join(dir, ".env");
+		if (!existsSync(p)) continue;
+		for (const line of readFileSync(p, "utf8").split("\n")) {
+			const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);
+			if (!m || !m[2] || process.env[m[1]]) continue;
+			process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+		}
+	}
+}
+
+function num(name: string, fallback: number): number {
+	const v = process.env[name];
+	if (v === undefined || v === "") return fallback;
+	const n = Number(v);
+	return Number.isFinite(n) ? n : fallback;
+}
+
+export function loadConfig(): Config {
+	loadDotEnv();
+	const envMode = process.env.JEV_LENS_MODE;
+	const mode: SealMode = envMode === "batch" || envMode === "budget" || envMode === "rolling" ? envMode : "budget";
+	return {
+		enabled: process.env.JEV_LENS_DISABLED !== "1",
+		mode,
+		budgetFraction: num("JEV_LENS_BUDGET_FRACTION", 0.5),
+		budgetMinTokens: num("JEV_LENS_BUDGET_MIN_TOKENS", 1000),
+		forgetBelow: num("JEV_LENS_FORGET_BELOW", 0.25),
+		trimBelow: num("JEV_LENS_TRIM_BELOW", 0.5),
+		trimAbove: num("JEV_LENS_TRIM_ABOVE", 0.6),
+		durableAbove: num("JEV_LENS_DURABLE_ABOVE", 0.7),
+		minTokens: num("JEV_LENS_MIN_TOKENS", 150),
+		classifyWaitMs: num("JEV_LENS_CLASSIFY_WAIT_MS", 2500),
+		cacheTtlMs: num("JEV_LENS_CACHE_TTL_MS", 5 * 60 * 1000),
+		trimHeadLines: num("JEV_LENS_TRIM_HEAD", 15),
+		trimTailLines: num("JEV_LENS_TRIM_TAIL", 15),
+		stateHeadChars: num("JEV_LENS_STATE_HEAD", 2500),
+		stateTailChars: num("JEV_LENS_STATE_TAIL", 800),
+		presend: process.env.JEV_LENS_PRESEND !== "0",
+		presendMinTokens: num("JEV_LENS_PRESEND_MIN_TOKENS", 1200),
+		presendNeedsFullAbove: num("JEV_LENS_PRESEND_NEEDS_FULL_ABOVE", 0.5),
+		presendFullMassAbove: num("JEV_LENS_PRESEND_FULL_MASS_ABOVE", 0.5),
+		presendCodeNeedsFullAbove: num("JEV_LENS_PRESEND_CODE_NEEDS_FULL_ABOVE", 0.5),
+		presendCommandNeedsFullAbove: num("JEV_LENS_PRESEND_COMMAND_NEEDS_FULL_ABOVE", 0.65),
+		presendCodePolicy: process.env.JEV_LENS_PRESEND_CODE_POLICY === "outline" ? "outline" : "gate",
+		presendMinConfidence: num("JEV_LENS_PRESEND_MIN_CONFIDENCE", 0),
+		presendExpandAbove: num("JEV_LENS_PRESEND_EXPAND_ABOVE", 0.5),
+		presendCommandPolicy: process.env.JEV_LENS_PRESEND_COMMAND_POLICY === "gate" ? "gate" : "sections",
+		presendSectionExpandAbove: num("JEV_LENS_PRESEND_SECTION_EXPAND_ABOVE", 0.5),
+		presendSectionFloor: num("JEV_LENS_PRESEND_SECTION_FLOOR", 0.3),
+		model: process.env.JEV_LENS_MODEL || "jev-latest",
+		variantFile: process.env.JEV_LENS_VARIANT || undefined,
+		forceMock: process.env.JEV_LENS_CLASSIFIER === "mock",
+		logFile: process.env.JEV_LENS_LOG !== "0",
+		apiKey: resolveApiKey(),
+	};
+}
+
+export interface VariantOverrides {
+	name?: string;
+	config?: Partial<Config>;
+	prompts?: Record<string, unknown>;
+	views?: Record<string, number>;
+}
+
+/** Read a variant file (either a bare variant or an autoresearch best.json with { variant }). */
+export function loadVariant(path: string | undefined): VariantOverrides {
+	if (!path) return {};
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8")) as VariantOverrides & { variant?: VariantOverrides };
+		return raw.variant ?? raw;
+	} catch {
+		return {};
+	}
+}
+
+/** Config with a variant's config overrides applied. */
+export function loadConfigWithVariant(): { cfg: Config; variant: VariantOverrides } {
+	const base = loadConfig();
+	const variant = loadVariant(base.variantFile);
+	return { cfg: { ...base, ...(variant.config ?? {}) }, variant };
+}

package/src/ledger.ts

@@ -0,0 +1,25 @@
+import type { Decision } from "./types.ts";
+
+export const ENTRY_TYPE = "jev-lens";
+
+export interface LedgerEntryData {
+	kind: "decision";
+	decision: Decision;
+}
+
+/** Rebuild the decision map from persisted custom entries (survives resume, reload, fork). */
+export function rebuildLedger(entries: Iterable<unknown>): Map<string, Decision> {
+	const ledger = new Map<string, Decision>();
+	for (const e of entries) {
+		const entry = e as { type?: string; customType?: string; data?: LedgerEntryData };
+		if (entry.type !== "custom" || entry.customType !== ENTRY_TYPE || !entry.data) continue;
+		if (entry.data.kind === "decision") {
+			const d = entry.data.decision;
+			const prev = ledger.get(d.id);
+			// Later entries win; an applied entry never regresses to pending.
+			if (prev?.status === "applied" && d.status === "pending") continue;
+			ledger.set(d.id, { ...d });
+		}
+	}
+	return ledger;
+}

package/src/memory-file.ts

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { DurableNote } from "./types.ts";
+
+export const MEMORY_MAX_LINES = 150;
+export const MEMORY_MAX_CHARS = 8000;
+
+function hash(s: string): string {
+	let h = 0;
+	for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) | 0;
+	return (h >>> 0).toString(16);
+}
+
+export function readMemoryFile(path: string): string {
+	return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+
+/** Append durable notes as bullet lines, dedup by normalized text, cap size keeping the newest. */
+export function appendNotes(path: string, notes: DurableNote[]): number {
+	if (notes.length === 0) return 0;
+	const existing = readMemoryFile(path);
+	const lines = existing.split("\n").filter((l) => l.startsWith("- "));
+	const seen = new Set(lines.map((l) => hash(l.replace(/^- \(\S+, \w+\) /, "").trim().toLowerCase())));
+	let added = 0;
+	for (const n of notes) {
+		const text = n.text.replace(/\s+/g, " ").trim();
+		if (!text) continue;
+		const key = hash(text.toLowerCase());
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const date = new Date(n.at).toISOString().slice(0, 10);
+		lines.push(`- (${date}, ${n.source}) ${text.length > 400 ? `${text.slice(0, 400)}…` : text}`);
+		added++;
+	}
+	if (added === 0) return 0;
+	let kept = lines.slice(-MEMORY_MAX_LINES);
+	while (kept.join("\n").length > MEMORY_MAX_CHARS && kept.length > 1) kept = kept.slice(1);
+	const header = "# jev-lens\n\nDurable notes selected by jev from earlier sessions. Newest last.\n\n";
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${header}${kept.join("\n")}\n`, "utf8");
+	return added;
+}
+
+export function memoryPromptSection(snapshot: string): string {
+	const body = snapshot
+		.split("\n")
+		.filter((l) => l.startsWith("- "))
+		.join("\n");
+	if (!body) return "";
+	return `\n\n# Memory from earlier sessions (jev-lens)\nThese notes were kept from previous sessions in this project. Treat them as likely but verify before relying on details.\n${body}\n`;
+}

package/src/pi-types.ts

@@ -0,0 +1,6 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+/** pi's AgentMessage union, taken from the context event so we track pi's own definition. */
+export type AgentMessage = ContextEvent["messages"][number];
+export type ToolResultMessage = Extract<AgentMessage, { role: "toolResult" }>;
+export type AssistantMessage = Extract<AgentMessage, { role: "assistant" }>;

package/src/policy.ts

@@ -0,0 +1,145 @@
+import type { AgentMessage, ToolResultMessage } from "./pi-types.ts";
+import type { Config } from "./config.ts";
+import type { Bucket, Decision } from "./types.ts";
+import { contentText, estimateTokensOfText } from "./text.ts";
+
+export const STUB_PREFIX = "[jev-lens pruned:";
+
+export function stubText(summary: string): string {
+	return `${STUB_PREFIX} ${summary}. The output was judged no longer needed; call the tool again if you need it.]`;
+}
+
+export function trimText(text: string, headLines: number, tailLines: number): string {
+	const lines = text.split("\n");
+	if (lines.length <= headLines + tailLines + 2) return text;
+	const dropped = lines.length - headLines - tailLines;
+	return [
+		...lines.slice(0, headLines),
+		`[jev-lens trimmed ${dropped} lines here; only the head and tail were judged useful. Call the tool again for the full output.]`,
+		...lines.slice(-tailLines),
+	].join("\n");
+}
+
+/** Deterministic transform of a tool result given a frozen decision. */
+export function transformToolResult(message: AgentMessage, decision: Decision, cfg: Config): AgentMessage {
+	if (message.role !== "toolResult" || decision.bucket === "keep") return message;
+	// Classifiers only see text; never apply even a restored decision to unseen image content.
+	if (message.content.some((c) => c.type !== "text")) return message;
+	const original = contentText(message.content);
+	const text = decision.bucket === "forget" ? stubText(decision.summary) : trimText(original, cfg.trimHeadLines, cfg.trimTailLines);
+	return { ...message, content: [{ type: "text", text }] };
+}
+
+export function decideBucket(p: { needed: number; outcomeOnly: number }, cfg: Config): Bucket {
+	if (p.needed < cfg.forgetBelow) return "forget";
+	if (p.needed < cfg.trimBelow && p.outcomeOnly > cfg.trimAbove) return "trim";
+	return "keep";
+}
+
+/**
+ * Tokens that pending (not yet applied) decisions would remove from this message list, and the
+ * size of the tail that applying them would rewrite (everything from the first pending decision on).
+ */
+export function pendingPrunable(messages: AgentMessage[], ledger: Map<string, Decision>, cfg: Config): { tokens: number; tailTokens: number } {
+	let tokens = 0;
+	let tailTokens = 0;
+	let inTail = false;
+	for (const m of messages) {
+		const size = estimateTokensOfText(contentText((m as { content?: unknown }).content));
+		if (m.role === "toolResult") {
+			const d = ledger.get(m.toolCallId);
+			if (d && d.status === "pending" && d.bucket !== "keep") {
+				const after = estimateTokensOfText(contentText((transformToolResult(m, d, cfg) as ToolResultMessage).content));
+				tokens += Math.max(0, size - after);
+				inTail = true;
+			}
+		}
+		if (inTail) tailTokens += size;
+	}
+	return { tokens, tailTokens };
+}
+
+/**
+ * Decide whether this call should apply pending decisions, given the mode and cache state.
+ * Budget mode reasons about the cache: applying rewrites the tail once (tailTokens at full price
+ * instead of the cached rate), and then saves `tokens` at the cached rate on every later call.
+ * With a 10x cache discount that pays back after ~9 × tailTokens / tokens calls, so we apply
+ * when the prunable share of the tail is at least `budgetFraction`.
+ */
+export function shouldApplyPending(
+	mode: Config["mode"],
+	cfg: Config,
+	coldCache: boolean,
+	pending: { tokens: number; tailTokens: number },
+): { apply: boolean; reason: string } {
+	if (coldCache) return { apply: true, reason: "cold-cache" };
+	if (mode === "rolling") return { apply: true, reason: "rolling" };
+	if (mode === "budget" && pending.tokens >= cfg.budgetMinTokens && pending.tokens >= cfg.budgetFraction * pending.tailTokens) {
+		return { apply: true, reason: "budget" };
+	}
+	return { apply: false, reason: mode };
+}
+
+export interface ApplyResult {
+	messages: AgentMessage[];
+	tokensOriginal: number;
+	tokensSent: number;
+	appliedNow: Decision[];
+	frozen: number;
+	pendingHeld: number;
+}
+
+/**
+ * Apply the ledger to the outgoing message list.
+ * - Frozen (applied) decisions are always re-applied identically, so the prompt prefix stays stable.
+ * - Pending decisions are applied now only if `applyPending` is true; they then freeze.
+ * - Messages without a decision pass through untouched. Tool results are never removed,
+ *   only rewritten, because every function_call needs a matching output.
+ */
+export function applyLedger(
+	messages: AgentMessage[],
+	ledger: Map<string, Decision>,
+	cfg: Config,
+	applyPending: boolean,
+	callIndex: number,
+	reason: string,
+): ApplyResult {
+	const out: AgentMessage[] = [];
+	const appliedNow: Decision[] = [];
+	let frozen = 0;
+	let pendingHeld = 0;
+	let tokensOriginal = 0;
+	let tokensSent = 0;
+	for (const m of messages) {
+		if (m.role !== "toolResult") {
+			out.push(m);
+			continue;
+		}
+		const before = estimateTokensOfText(contentText(m.content));
+		tokensOriginal += before;
+		const d = ledger.get(m.toolCallId);
+		if (!d || d.bucket === "keep") {
+			out.push(m);
+			tokensSent += before;
+			continue;
+		}
+		if (d.status === "pending") {
+			if (!applyPending) {
+				pendingHeld++;
+				out.push(m);
+				tokensSent += before;
+				continue;
+			}
+			d.status = "applied";
+			d.appliedAtCall = callIndex;
+			d.appliedReason = reason;
+			appliedNow.push(d);
+		} else {
+			frozen++;
+		}
+		const t = transformToolResult(m, d, cfg) as ToolResultMessage;
+		out.push(t);
+		tokensSent += estimateTokensOfText(contentText(t.content));
+	}
+	return { messages: out, tokensOriginal, tokensSent, appliedNow, frozen, pendingHeld };
+}