@prometheus-ai/snapcompact 0.5.8

package/src/snapcompact.ts

@@ -0,0 +1,1290 @@
+/**
+ * Snapcompact compaction: archive conversation history as dense bitmap images.
+ *
+ * Instead of asking an LLM to summarize discarded history, the serialized
+ * conversation is rendered into PNG frames of pixel-font text that vision
+ * models read back directly, like an archivist at a snapcompact frame
+ * reader. Frames are `frameSize` wide; their height hugs the text rows
+ * actually printed, so a partially filled frame never bills blank rows.
+ *
+ * The frame shape is provider-aware. Original choices came from the SQuAD
+ * prose evals (`packages/snapcompact`, 200k-token monolithic runs); the
+ * spacing choices below come from the tool-result legibility bench
+ * (`research/toolbench.py`, real search/read/find output with structure QA),
+ * which exposed that the prose-tuned dense cells erase the line numbers and
+ * indentation that code/search output depends on:
+ *
+ * - **Anthropic** (`11on16-bw`): 8x13 glyphs on an 11px advance (extra
+ *   letter-spacing), black ink. On the tool-result bench, tracking the
+ *   readable cell beat plain `8on16-bw` (opus-4.8 f1 .806 vs .755) and far
+ *   beat the prior dense `6x12-dim` (.351, which fell below the OCR ~16px/char
+ *   floor and abstained). Opus 4.7+/Fable/Mythos ingest high-res natively
+ *   (2576px edge, 4,784 visual-token cap), so those lines get 1932px frames:
+ *   same bill, fewer frames. Older Claude lines downscale past 1568px.
+ * - **Google** (`8on22-bw` @2048): 8x13 glyphs on a 22px pitch (extra line
+ *   spacing), black ink. Leading lifted gemini-3.5-flash to f1 .934 vs .807
+ *   for `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`. Gemini 3.x
+ *   bills a fixed `media_resolution` budget per image (default 1,120 tokens)
+ *   regardless of pixels, so the 2048px frame carries more chars at the same
+ *   bill.
+ * - **OpenAI** (`8on22-bw`): same leading win (gpt-5.5/gpt-5.4-mini). Patch
+ *   billing (32px × 1.2, 10k-patch budget at `detail: "original"`) is
+ *   area-proportional, so resolution cannot improve chars/$ — 1568 stays.
+ *   `detail: "high"` would downgrade (2,500-patch cap); `original` is sent.
+ * - **Unknown providers** default to the Anthropic shape. Gateways can
+ *   defeat any shape silently: OpenRouter enforces a per-model image cap
+ *   (measured: 8 images for glm-4.6v — frames past the cap are dropped with
+ *   no error, billed tokens plateau exactly at 8x frame cost). The same
+ *   frames routed direct to the vendor read fine (glm f1 .20 -> .78), so
+ *   `providerImageBudget` caps per-request images per provider (OpenRouter
+ *   8, unknown 5) and `compact()` keeps any archive overflow as a text tail
+ *   on the summary instead of rendering frames that would be dropped.
+ *
+ * The whole pass is local and deterministic — no LLM call, no API key, no
+ * latency beyond rendering. Rasterization and PNG encoding happen in native
+ * code (`renderSnapcompactPng` in `crates/prometheus-natives/src/snapcompact.rs`).
+ * Frames persist in the compaction entry's `preserveData` and are
+ * re-attached to the compaction summary message on every context rebuild.
+ */
+
+import type { Api, ImageContent, Message, Model } from "@prometheus-ai/ai";
+import { renderSnapcompactPng } from "@prometheus-ai/natives";
+import { formatGroupedPaths, prompt } from "@prometheus-ai/utils";
+import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
+import snapcompactSummaryPrompt from "./prompts/snapcompact-summary.md" with { type: "text" };
+
+// ============================================================================
+// Shapes
+// ============================================================================
+
+/** One eval-validated frame shape: font, cell, ink, repetition, and size. */
+export interface Shape {
+	/** Bundled font in the native renderer. */
+	font: "5x8" | "8x8" | "6x12" | "8x13";
+	/** Target cell advance in pixels; differing from the font's natural cell
+	 *  renders via Lanczos stretch (anti-aliased RGB frame). */
+	cellWidth: number;
+	/** Target cell pitch in pixels. */
+	cellHeight: number;
+	/** `false` → glyphs drawn at natural size on the cell pitch (8on16);
+	 *  `true`/`undefined` → legacy auto Lanczos stretch when cell ≠ natural. */
+	stretch?: boolean;
+	/** Ink: `sent` cycles six hues at sentence boundaries; `bw` is black. */
+	variant: "sent" | "bw";
+	/** Print stopwords in dim ink (research `dim`/`sent-dim` variants). */
+	stopwordDim?: boolean;
+	/** 1/undefined = row-major grid; 2 = two word-wrapped newspaper columns
+	 *  (research `doc`). */
+	columns?: number;
+	/** Each text line is printed this many times; copies after the first sit
+	 *  on a pale highlight band (redundancy coding). */
+	lineRepeat: number;
+	/** Frame edge in pixels. */
+	frameSize: number;
+	/** Per-frame billed-token estimate for the shape's target provider. */
+	frameTokenEstimate: number;
+	/** Resolution hint attached to frame images (OpenAI-only). */
+	imageDetail?: ImageContent["detail"];
+}
+
+/** Geometry half of a {@link Shape}: everything except provider billing. */
+export type ShapeGeometry = Omit<Shape, "frameTokenEstimate" | "imageDetail">;
+
+/**
+ * Frame variants exercised by the SQuAD evals in `research/` that the native
+ * renderer reproduces faithfully, keyed by their research names. Font codes:
+ * `8x8u` unscii square cell, `8x8r` unscii with every line printed twice
+ * (redundancy coding), `6x6u` unscii Lanczos-squeezed to 6x6 (densest
+ * readable cell), `5x8` the X.org legacy font on its 2576px frame, `6x12`
+ * and `8x13` the X.org misc fonts, `8on16` 8x13 glyphs on an 8x16 cell pitch
+ * (no stretch, extra leading), `8on22` the same glyphs on a 22px pitch (more
+ * leading), `11on16` the same glyphs on an 11px advance (more tracking),
+ * `doc-` prefixed shapes a two-column word-wrapped newspaper layout. Ink:
+ * `sent` cycles six hues at sentence boundaries, `bw` is plain black, `-dim`
+ * suffix prints stopwords in gray.
+ */
+export const SHAPE_VARIANTS = {
+	"8x8r-bw": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "bw", lineRepeat: 2, frameSize: 1568 },
+	"8x8r-sent": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "sent", lineRepeat: 2, frameSize: 1568 },
+	"8x8u-bw": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"8x8u-sent": { font: "8x8", cellWidth: 8, cellHeight: 8, variant: "sent", lineRepeat: 1, frameSize: 1568 },
+	"6x6u-bw": { font: "8x8", cellWidth: 6, cellHeight: 6, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"6x6u-sent": { font: "8x8", cellWidth: 6, cellHeight: 6, variant: "sent", lineRepeat: 1, frameSize: 1568 },
+	"5x8-bw": { font: "5x8", cellWidth: 5, cellHeight: 8, variant: "bw", lineRepeat: 1, frameSize: 2576 },
+	"5x8-sent": { font: "5x8", cellWidth: 5, cellHeight: 8, variant: "sent", lineRepeat: 1, frameSize: 2576 },
+	"6x12-dim": {
+		font: "6x12",
+		cellWidth: 6,
+		cellHeight: 12,
+		variant: "bw",
+		stopwordDim: true,
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"8x13-bw": { font: "8x13", cellWidth: 8, cellHeight: 13, variant: "bw", lineRepeat: 1, frameSize: 1568 },
+	"8on16-bw": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
+		variant: "bw",
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"8on22-bw": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 22,
+		stretch: false,
+		variant: "bw",
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"11on16-bw": {
+		font: "8x13",
+		cellWidth: 11,
+		cellHeight: 16,
+		stretch: false,
+		variant: "bw",
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"doc-8on16-bw": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
+		variant: "bw",
+		columns: 2,
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"doc-8on16-sent": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
+		variant: "sent",
+		columns: 2,
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+	"doc-8on16-sent-dim": {
+		font: "8x13",
+		cellWidth: 8,
+		cellHeight: 16,
+		stretch: false,
+		variant: "sent",
+		stopwordDim: true,
+		columns: 2,
+		lineRepeat: 1,
+		frameSize: 1568,
+	},
+} as const satisfies Record<string, ShapeGeometry>;
+
+/** Research name of one renderable frame variant. */
+export type ShapeVariantName = keyof typeof SHAPE_VARIANTS;
+
+/** All variant names, in declaration order (for settings enums). */
+export const SHAPE_VARIANT_NAMES = Object.keys(SHAPE_VARIANTS) as readonly ShapeVariantName[];
+
+/** Runtime guard for variant names loaded from config. */
+export function isShapeVariantName(value: unknown): value is ShapeVariantName {
+	return typeof value === "string" && value in SHAPE_VARIANTS;
+}
+
+/** Provider families with distinct image billing. */
+type BillingFamily = "anthropic" | "google" | "openai";
+
+function billingFamily(api?: Api): BillingFamily {
+	switch (api) {
+		case "openai-completions":
+		case "openai-responses":
+		case "openai-codex-responses":
+		case "azure-openai-responses":
+			return "openai";
+		case "google-generative-ai":
+		case "google-gemini-cli":
+		case "google-vertex":
+			return "google";
+		default:
+			// anthropic-messages, bedrock-converse-stream, and anything unknown
+			// share Anthropic's pixel-area pricing as the safe ceiling.
+			return "anthropic";
+	}
+}
+
+/**
+ * Per-frame billing for a square frame of edge `frameSize`, by family.
+ * Formulas verified against live bills in the resolution benchmarks:
+ * - Anthropic: 28px patches, capped at 4,784 visual tokens (the API
+ *   downscales past the cap; 1568 → 3,136 measured) + 5% margin.
+ * - Google: Gemini 3.x bills a fixed `media_resolution` budget per image —
+ *   default HIGH = 1,120 tokens — regardless of pixel size.
+ * - OpenAI: 32px patches × 1.2 flagship multiplier, 10,000-patch budget at
+ *   `detail: "original"` (1568 → 2,881 measured).
+ */
+function familyBilling(family: BillingFamily, frameSize: number): Pick<Shape, "frameTokenEstimate" | "imageDetail"> {
+	switch (family) {
+		case "google":
+			return { frameTokenEstimate: 1120 };
+		case "openai": {
+			const patches = Math.min(Math.ceil(frameSize / 32) ** 2, 10_000);
+			return { frameTokenEstimate: Math.ceil(patches * 1.2), imageDetail: "original" };
+		}
+		default: {
+			const patches = Math.min(Math.ceil(frameSize / 28) ** 2, 4784);
+			return { frameTokenEstimate: Math.ceil(patches * 1.05) };
+		}
+	}
+}
+
+/** Attach a provider family's billing to a variant geometry. */
+function priceShape(base: ShapeGeometry, family: BillingFamily): Shape {
+	return { ...base, ...familyBilling(family, base.frameSize) };
+}
+
+/** Eval-validated shapes, keyed by the provider family they won on. */
+export const SHAPES = {
+	/** `11on16-bw`: 8x13 glyphs on an 11px advance (extra tracking), black ink.
+	 *  Tool-result legibility bench (real search/read/find output, structure QA)
+	 *  on opus-4.8: f1 .806 vs .755 for plain `8on16-bw` and .351 for the prior
+	 *  `6x12-dim` default — letter-spacing the readable cell wins; the dense
+	 *  6x12 was below the OCR ~16px/char floor and abstained. */
+	anthropic: priceShape(SHAPE_VARIANTS["11on16-bw"], "anthropic"),
+	/** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
+	 *  Tool-result legibility bench on gemini-3.5-flash: f1 .934 vs .807 for
+	 *  plain `8on16-bw` and .287 for the prior `doc-8on16-sent-dim`; the
+	 *  line-spacing reduces row crowding so line numbers stay legible. */
+	google: priceShape(SHAPE_VARIANTS["8on22-bw"], "google"),
+	/** `8on22-bw`: 8x13 glyphs on a 22px pitch (extra leading), black ink.
+	 *  Same line-spacing win for OpenAI; bench on gpt-5.5/gpt-5.4-mini showed
+	 *  leading lifts recall on the readable cell over plain `8on16-bw`. */
+	openai: priceShape(SHAPE_VARIANTS["8on22-bw"], "openai"),
+	/** Original 5x8 X.org shape (pre-shape-table sessions rendered this). */
+	legacy: priceShape(SHAPE_VARIANTS["5x8-sent"], "anthropic"),
+} satisfies Record<string, Shape>;
+
+/** Runtime guard for shape overrides loaded from config or preserve data. */
+export function isShape(value: unknown): value is Shape {
+	if (!value || typeof value !== "object") return false;
+	const shape = value as Record<string, unknown>;
+	const font = shape.font;
+	const variant = shape.variant;
+	const detail = shape.imageDetail;
+	return (
+		(font === "5x8" || font === "8x8" || font === "6x12" || font === "8x13") &&
+		typeof shape.cellWidth === "number" &&
+		shape.cellWidth > 0 &&
+		typeof shape.cellHeight === "number" &&
+		shape.cellHeight > 0 &&
+		(shape.stretch === undefined || typeof shape.stretch === "boolean") &&
+		(variant === "sent" || variant === "bw") &&
+		(shape.stopwordDim === undefined || typeof shape.stopwordDim === "boolean") &&
+		(shape.columns === undefined || shape.columns === 1 || shape.columns === 2) &&
+		typeof shape.lineRepeat === "number" &&
+		shape.lineRepeat > 0 &&
+		typeof shape.frameSize === "number" &&
+		shape.frameSize > 0 &&
+		typeof shape.frameTokenEstimate === "number" &&
+		shape.frameTokenEstimate > 0 &&
+		(detail === undefined || detail === "auto" || detail === "low" || detail === "high" || detail === "original")
+	);
+}
+
+/** Eval-winning variant per provider family (billing fallback when the
+ *  model id matches no known reader line). */
+const FAMILY_VARIANT: Record<BillingFamily, ShapeVariantName> = {
+	anthropic: "11on16-bw",
+	google: "8on22-bw",
+	openai: "8on22-bw",
+};
+
+const FAMILY_SHAPE: Record<BillingFamily, Shape> = {
+	anthropic: SHAPES.anthropic,
+	google: SHAPES.google,
+	openai: SHAPES.openai,
+};
+
+/** One model line's ideal format: variant plus an optional frame-size
+ *  override when the line reads larger frames at no extra cost. */
+export interface IdealShape {
+	variant: ShapeVariantName;
+	frameSize?: number;
+}
+
+/** Eval-winning format per model line, matched against the model id. The
+ *  wire API only identifies the gateway — a Claude served through Vertex or
+ *  OpenRouter still reads best with its own shape. Patterns cover the model
+ *  lines the mono evals measured; everything else falls back to the API
+ *  family's winner at the standard 1568px frame. First match wins. */
+const MODEL_VARIANTS: readonly (readonly [RegExp, IdealShape])[] = [
+	// Opus 4.7+ and Fable/Mythos read high-res natively (2576px edge under a
+	// 4,784 visual-token cap → 1932px square sweet spot): same recall and
+	// cost as 1568, a third fewer frames.
+	[/claude.*(fable|mythos)/i, { variant: "11on16-bw", frameSize: 1932 }],
+	[/claude-?opus-?4[.-][7-9]/i, { variant: "11on16-bw", frameSize: 1932 }],
+	// Older Claude lines downscale past 1568px — keep the safe size.
+	[/claude/i, { variant: "11on16-bw" }],
+	// Gemini 3.x bills a fixed 1,120-token budget per image regardless of
+	// pixels: 2048px packs more chars per frame at the same bill.
+	[/gemini/i, { variant: "8on22-bw", frameSize: 2048 }],
+	// gpt-5.5 patch billing is area-proportional; 1568 is already optimal.
+	[/gpt|codex/i, { variant: "8on22-bw" }],
+	// kimi's image processor downscales past 1792px (64×64 28px patches);
+	// 1568 wins on chars/$ and reads at f1 .973 (≤8 frames per request).
+	[/kimi/i, { variant: "8on16-bw" }],
+	// glm-4.6v .780 mono via direct vendor routing.
+	[/glm/i, { variant: "8on16-bw" }],
+];
+
+/** Eval-ideal format for a model id, or undefined when unmeasured. */
+export function idealShapeVariant(modelId: string): IdealShape | undefined {
+	return MODEL_VARIANTS.find(([pattern]) => pattern.test(modelId))?.[1];
+}
+
+/** What will read the frames: the wire API (billing) and model id (shape). */
+export interface ShapeTarget {
+	api?: Api;
+	id?: string;
+}
+
+/**
+ * Pick the frame shape for a reader. An explicit `variant` (anything but
+ * `"auto"`) forces that geometry; otherwise the model id selects the
+ * eval-winning shape — and frame size — for its model line, falling back to
+ * the API family's winner when the model is unmeasured. Billing (token
+ * estimate, detail hint) always follows the API family actually carrying
+ * the request, computed for the resolved frame size. Accepts a full Prometheus AI
+ * `Model` or any `{ api, id }` subset.
+ */
+export function resolveShape(model?: ShapeTarget, variant?: ShapeVariantName | "auto"): Shape {
+	const family = billingFamily(model?.api);
+	if (variant && variant !== "auto") return priceShape(SHAPE_VARIANTS[variant], family);
+	const ideal = model?.id ? idealShapeVariant(model.id) : undefined;
+	const name = ideal?.variant ?? FAMILY_VARIANT[family];
+	if (name === FAMILY_VARIANT[family] && ideal?.frameSize === undefined) return FAMILY_SHAPE[family];
+	const base = SHAPE_VARIANTS[name];
+	return priceShape(ideal?.frameSize ? { ...base, frameSize: ideal.frameSize } : base, family);
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Legacy frame edge in pixels (the 5x8 shape's eval-validated size). New
+ *  shapes carry their own `frameSize`. */
+export const FRAME_SIZE = 2576;
+
+/** Maximum frames carried on a compaction entry. Oldest frames are dropped
+ *  first once the budget is exceeded (mirrors how iterative text summaries
+ *  fade the oldest detail). */
+export const MAX_FRAMES = 8;
+
+/** Conservative per-frame token estimate used for context budgeting
+ *  (upper bound across shapes: Anthropic bills 1568*1568/750 ≈ 3,278). */
+export const FRAME_TOKEN_ESTIMATE = 3300;
+
+/**
+ * Per-request image-count budgets by provider id. Routers and smaller
+ * providers enforce hard caps and silently DROP images past them (measured:
+ * OpenRouter caps at 8 — images 9+ vanish with no error and billed tokens
+ * plateau at 8x frame cost). First-party APIs allow far more; their values
+ * are conservative policy caps well under the measured hard limits
+ * (Anthropic 100, OpenAI 500, Gemini ~2500).
+ */
+export const PROVIDER_IMAGE_BUDGETS: Record<string, number> = {
+	anthropic: 90,
+	"amazon-bedrock": 90,
+	openai: 200,
+	google: 200,
+	"google-vertex": 200,
+	"google-gemini-cli": 200,
+	openrouter: 8,
+};
+
+/** Safe floor for unknown providers (strictest mainstream measured: Groq ~5). */
+export const DEFAULT_PROVIDER_IMAGE_BUDGET = 5;
+
+/** Per-request image budget for `provider`; unknown providers get the floor. */
+export function providerImageBudget(provider: string | undefined): number {
+	return (provider !== undefined ? PROVIDER_IMAGE_BUDGETS[provider] : undefined) ?? DEFAULT_PROVIDER_IMAGE_BUDGET;
+}
+
+/** Archive frame budget for `provider`: its image budget clamped to {@link MAX_FRAMES}. */
+export function providerFrameBudget(provider: string | undefined): number {
+	return Math.min(MAX_FRAMES, providerImageBudget(provider));
+}
+
+/** Key under `CompactionEntry.preserveData` holding the frame archive. */
+export const PRESERVE_KEY = "snapcompact";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** One developed snapcompact frame: a base64 PNG plus its reading geometry. */
+export interface Frame {
+	/** Base64-encoded PNG. */
+	data: string;
+	mimeType: string;
+	/** Characters per row in the frame grid (per-column width on doc frames). */
+	cols: number;
+	/** Text rows in the frame grid (unique lines, not repeated copies). */
+	rows: number;
+	/** Characters actually printed onto this frame. */
+	chars: number;
+	/** Shape metadata (absent on legacy frames, which are 5x8 `sent`). */
+	font?: Shape["font"];
+	variant?: Shape["variant"];
+	lineRepeat?: number;
+	/** 2 on two-column doc frames; absent on row-major grid frames. */
+	columns?: number;
+	/** True when stopwords were printed in dim ink. */
+	stopwordDim?: boolean;
+	/** Resolution hint forwarded to the provider when re-attaching. */
+	detail?: ImageContent["detail"];
+}
+
+/** Frame archive persisted under `preserveData[PRESERVE_KEY]`. */
+export interface Archive {
+	/** Frames ordered oldest to newest. */
+	frames: Frame[];
+	/** Characters currently readable across all frames. */
+	totalChars: number;
+	/** Characters dropped so far to respect the frame budget. */
+	truncatedChars: number;
+	/** Most recent slice of archived history that exceeded the frame budget,
+	 *  kept verbatim as normalized text (dim markers and newline glyphs
+	 *  included). Shipped as plain text in the compaction summary and folded
+	 *  back into frames by the next compaction. */
+	textTail?: string;
+}
+
+export interface Geometry {
+	/** Characters per row (per-column line width when `columns === 2`). */
+	cols: number;
+	rows: number;
+	/** Characters that fit one frame (nominal upper bound on doc shapes,
+	 *  where real consumption is wrap-dependent). */
+	capacity: number;
+}
+
+export interface Options<TMessage = Message> extends SerializeOptions {
+	/** App-level message transformer (same contract as agent-core's `SummaryOptions.convertToLlm`). */
+	convertToLlm?: ConvertToLlm<TMessage>;
+	/** Model whose provider API selects the frame shape. */
+	model?: Pick<Model, "api">;
+	/** Caller-owned reasoning/thinking level metadata; currently preserved for compatibility. */
+	thinkingLevel?: unknown;
+	/** Explicit shape override; wins over `model`. */
+	shape?: Shape;
+	/** Frame edge in pixels. Defaults to the shape's `frameSize`. */
+	frameSize?: number;
+	/** Frame budget. Defaults to {@link MAX_FRAMES}. */
+	maxFrames?: number;
+}
+
+/** Result of rendering one frame. */
+export interface RenderedFrame {
+	/** Base64-encoded PNG, as returned by the native renderer. */
+	data: string;
+	cols: number;
+	rows: number;
+	/** Characters printed (ink toggles excluded; input may be shorter than capacity). */
+	chars: number;
+}
+
+// ============================================================================
+// Compaction data contracts
+// ============================================================================
+
+export interface FileOperations {
+	read: Set<string>;
+	written: Set<string>;
+	edited: Set<string>;
+}
+
+export interface CompactionDetails {
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+
+export interface CompactionPreparation<TMessage = Message> {
+	/** UUID of first entry to keep. */
+	firstKeptEntryId: string;
+	/** Messages that will be archived and discarded. */
+	messagesToSummarize: TMessage[];
+	/** Messages that will be archived as the split-turn prefix, if any. */
+	turnPrefixMessages: TMessage[];
+	tokensBefore: number;
+	/** Summary from previous compaction, for continuity when no prior snapcompact archive exists. */
+	previousSummary?: string;
+	/** Preserved opaque compaction payload from the previous compaction, if any. */
+	previousPreserveData?: Record<string, unknown>;
+	/** File operations extracted by the host agent. */
+	fileOps: FileOperations;
+}
+
+export interface CompactionResult<T = CompactionDetails> {
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	details?: T;
+	preserveData?: Record<string, unknown>;
+}
+
+export type ConvertToLlm<TMessage = Message> = (messages: TMessage[]) => Message[];
+
+function defaultConvertToLlm<TMessage>(messages: TMessage[]): Message[] {
+	return messages as unknown as Message[];
+}
+
+// ============================================================================
+// File operation helpers
+// ============================================================================
+
+export function createFileOps(): FileOperations {
+	return {
+		read: new Set(),
+		written: new Set(),
+		edited: new Set(),
+	};
+}
+
+export function computeFileLists(fileOps: FileOperations): CompactionDetails {
+	const modified = new Set([...fileOps.edited, ...fileOps.written]);
+	const readFiles = [...fileOps.read].filter(file => !modified.has(file)).sort();
+	const modifiedFiles = [...modified].sort();
+	return { readFiles, modifiedFiles };
+}
+
+/**
+ * Format file operations as one `<files>` tag: a grouped, prefix-folded
+ * directory tree (find-tool shape) with a ` (Read)` / ` (Write)` / ` (RW)`
+ * marker per file. `readSet` is the cumulative read set (`fileOps.read`),
+ * used to tell modified files that were also read (RW) from blind writes.
+ */
+const FILE_OPERATION_SUMMARY_LIMIT = 20;
+
+function stripFileOperationTags(summary: string): string {
+	// Legacy <read-files>/<modified-files> tags are still stripped so summaries
+	// written before the combined <files> tag self-heal on the next compaction.
+	return summary
+		.replace(/<files>[\s\S]*?<\/files>\s*/g, "")
+		.replace(/<read-files>[\s\S]*?<\/read-files>\s*/g, "")
+		.replace(/<modified-files>[\s\S]*?<\/modified-files>\s*/g, "")
+		.trimEnd();
+}
+
+function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string {
+	if (readFiles.length === 0 && modifiedFiles.length === 0) return "";
+	const mode = new Map<string, "Read" | "Write" | "RW">();
+	for (const file of readFiles) mode.set(file, "Read");
+	for (const file of modifiedFiles) mode.set(file, readSet?.has(file) ? "RW" : "Write");
+	const all = [...mode.keys()].sort();
+	let files = formatGroupedPaths(all.slice(0, FILE_OPERATION_SUMMARY_LIMIT), path => ` (${mode.get(path)})`);
+	if (all.length > FILE_OPERATION_SUMMARY_LIMIT) {
+		files += `\n… (${all.length - FILE_OPERATION_SUMMARY_LIMIT} more files omitted)`;
+	}
+	return prompt.render(fileOperationsTemplate, { files });
+}
+
+export function upsertFileOperations(
+	summary: string,
+	readFiles: string[],
+	modifiedFiles: string[],
+	readSet?: ReadonlySet<string>,
+): string {
+	const baseSummary = stripFileOperationTags(summary);
+	const fileOperations = formatFileOperations(readFiles, modifiedFiles, readSet);
+	if (!fileOperations) return baseSummary;
+	if (!baseSummary) return fileOperations;
+	return `${baseSummary}\n\n${fileOperations}`;
+}
+
+// ============================================================================
+// Message serialization
+// ============================================================================
+
+/** Default per-tool-result character cap in serialized history. */
+export const TOOL_RESULT_MAX_CHARS = 2000;
+
+/** Default per-argument-value character cap inside serialized tool calls
+ *  (write/edit bodies otherwise dump whole files into the archive). */
+export const TOOL_ARG_MAX_CHARS = 500;
+
+/** Default character cap across one tool call's full serialized argument list. */
+export const TOOL_CALL_MAX_CHARS = 2000;
+
+/** Default fraction of a truncation budget spent on the head; the remainder
+ *  keeps the tail, where command errors and test failures usually land. */
+export const TRUNCATE_HEAD_RATIO = 0.6;
+
+/** Zero-width ink toggles understood by the native renderer (shift-out/in):
+ *  text between them prints in dim gray ink without occupying a cell. */
+export const DIM_ON = "\u000e";
+export const DIM_OFF = "\u000f";
+
+/** Character budgets applied while serializing discarded history for frame
+ *  rendering. Pass `Infinity` to disable an individual cap. */
+export interface SerializeOptions {
+	/** Per-tool-result cap. Defaults to {@link TOOL_RESULT_MAX_CHARS}. */
+	toolResultMaxChars?: number;
+	/** Per-argument-value cap. Defaults to {@link TOOL_ARG_MAX_CHARS}. */
+	toolArgMaxChars?: number;
+	/** Whole-argument-list cap per call. Defaults to {@link TOOL_CALL_MAX_CHARS}. */
+	toolCallMaxChars?: number;
+	/** Head share of each budget, clamped to [0, 1]. Defaults to {@link TRUNCATE_HEAD_RATIO}. */
+	truncateHeadRatio?: number;
+	/** Print tool-result text in dim gray ink so archived conversation reads
+	 *  louder than archived tool noise. Defaults to `true`. */
+	dimToolResults?: boolean;
+}
+
+/** Keep the head and tail of `text`, eliding the middle beyond `maxChars`. */
+function truncateForSummary(text: string, maxChars: number, headRatio: number): string {
+	if (text.length <= maxChars) return text;
+	const ratio = Math.min(Math.max(headRatio, 0), 1);
+	const headChars = Math.round(maxChars * ratio);
+	const tailChars = maxChars - headChars;
+	const elided = text.length - maxChars;
+	const tail = tailChars > 0 ? text.slice(-tailChars) : "";
+	return `${text.slice(0, headChars)} [... ${elided} chars elided ...] ${tail}`;
+}
+
+const DIM_MARKERS = /[\u000e\u000f]/g;
+
+/** Cap on the unrendered archive text tail, in frame-capacity units: enough
+ *  to keep the newest discarded history readable without re-inflating the
+ *  context a compaction just shrank. */
+const TEXT_TAIL_MAX_PAGES = 2;
+
+/** Normalized archive text → plain text: drop zero-width dim toggles and
+ *  print newline glyphs as real newlines. */
+function toPlainText(text: string): string {
+	return stripDimMarkers(text).replaceAll(NEWLINE_GLYPH, "\n");
+}
+
+/** Strip stray ink toggles from raw content so it cannot forge dim spans. */
+function stripDimMarkers(text: string): string {
+	return text.replace(DIM_MARKERS, "");
+}
+
+export function serializeConversation(messages: Message[], options?: SerializeOptions): string {
+	const toolResultMaxChars = options?.toolResultMaxChars ?? TOOL_RESULT_MAX_CHARS;
+	const toolArgMaxChars = options?.toolArgMaxChars ?? TOOL_ARG_MAX_CHARS;
+	const toolCallMaxChars = options?.toolCallMaxChars ?? TOOL_CALL_MAX_CHARS;
+	const headRatio = options?.truncateHeadRatio ?? TRUNCATE_HEAD_RATIO;
+	const dimToolResults = options?.dimToolResults !== false;
+	const parts: string[] = [];
+
+	// Tool results flagged contextually useless (and their paired calls) carry
+	// no information worth archiving — skip the whole pair.
+	const uselessCallIds = new Set<string>();
+	for (const msg of messages) {
+		if (msg.role === "toolResult" && msg.useless === true && msg.isError !== true) {
+			uselessCallIds.add(msg.toolCallId);
+		}
+	}
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			const content =
+				typeof msg.content === "string"
+					? msg.content
+					: msg.content
+							.filter((content): content is { type: "text"; text: string } => content.type === "text")
+							.map(content => content.text)
+							.join("");
+			if (content) parts.push(`[User]: ${stripDimMarkers(content)}`);
+		} else if (msg.role === "assistant") {
+			const textParts: string[] = [];
+			const thinkingParts: string[] = [];
+			const toolCalls: string[] = [];
+
+			for (const block of msg.content) {
+				if (block.type === "text") {
+					textParts.push(stripDimMarkers(block.text));
+				} else if (block.type === "thinking") {
+					thinkingParts.push(stripDimMarkers(block.thinking));
+				} else if (block.type === "toolCall") {
+					if (uselessCallIds.has(block.id)) continue;
+					const args = block.arguments as Record<string, unknown>;
+					const argsStr = truncateForSummary(
+						Object.entries(args)
+							.map(
+								([key, value]) =>
+									`${key}=${truncateForSummary(JSON.stringify(value) ?? "undefined", toolArgMaxChars, headRatio)}`,
+							)
+							.join(", "),
+						toolCallMaxChars,
+						headRatio,
+					);
+					toolCalls.push(`${block.name}(${argsStr})`);
+				}
+			}
+
+			if (thinkingParts.length > 0) {
+				parts.push(`[Assistant thinking]: ${thinkingParts.join("\n")}`);
+			}
+			if (textParts.length > 0) {
+				parts.push(`[Assistant]: ${textParts.join("\n")}`);
+			}
+			if (toolCalls.length > 0) {
+				parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
+			}
+		} else if (msg.role === "toolResult") {
+			if (uselessCallIds.has(msg.toolCallId)) continue;
+			const content = msg.content
+				.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map(block => block.text)
+				.join("");
+			if (content) {
+				// Args above are JSON-escaped, so only raw result text can carry toggles.
+				const body = truncateForSummary(stripDimMarkers(content), toolResultMaxChars, headRatio);
+				parts.push(dimToolResults ? `[Tool result]: ${DIM_ON}${body}${DIM_OFF}` : `[Tool result]: ${body}`);
+			}
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+// ============================================================================
+// Preserve-data helpers
+// ============================================================================
+
+const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+
+function stripOpenAiRemoteCompactionPreserveData(
+	preserveData: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+	if (!preserveData || !(OPENAI_REMOTE_COMPACTION_PRESERVE_KEY in preserveData)) {
+		return preserveData;
+	}
+	const { [OPENAI_REMOTE_COMPACTION_PRESERVE_KEY]: _removed, ...rest } = preserveData;
+	return Object.keys(rest).length > 0 ? rest : undefined;
+}
+
+// ============================================================================
+// Text normalization
+// ============================================================================
+
+/** Folds for common non-Latin-1 characters the bundled fonts cannot draw. */
+const CHAR_FOLD: Record<string, string> = {
+	"\u2018": "'",
+	"\u2019": "'",
+	"\u201a": "'",
+	"\u201b": "'",
+	"\u201c": '"',
+	"\u201d": '"',
+	"\u201e": '"',
+	"\u2013": "-",
+	"\u2014": "-",
+	"\u2015": "-",
+	"\u2212": "-",
+	"\u2026": "...",
+	"\u2022": "*",
+	"\u25cf": "*",
+	"\u25a0": "*",
+	"\u25aa": "*",
+	"\u2190": "<-",
+	"\u2192": "->",
+	"\u21d2": "=>",
+	"\u2713": "v",
+	"\u2714": "v",
+	"\u2717": "x",
+	"\u2718": "x",
+};
+
+/** Printed in place of newline runs: the native renderer fills this cell
+ *  entirely with pitch-black ink, so line structure survives whitespace
+ *  collapsing at a one-cell cost. */
+export const NEWLINE_GLYPH = "\u2588";
+
+/** Collapsed in one pass: whitespace plus zero-width format characters (ZWSP,
+ *  BOM, directional marks — JS `\s` already counts BOM as whitespace, so they
+ *  must fold here, before the per-character pass). */
+const COLLAPSIBLE = /[\s\p{Cf}]+/gu;
+
+/** Runs carrying one of these collapse to {@link NEWLINE_GLYPH}. */
+const LINE_BREAK = /[\n\r\u2028\u2029]/;
+
+/** Leading/trailing spaces or newline glyphs add no information to a frame. */
+const EDGE_RUNS = /^[ \u2588]+|[ \u2588]+$/g;
+
+/** Glyph-less code points skipped outright instead of printing `?`: controls
+ *  (bare ESC/BEL/NUL — full ANSI sequences are stripped beforehand),
+ *  combining marks the fonts cannot compose, and lone surrogates. */
+const UNRENDERABLE = /[\p{Cc}\p{Mn}\p{Me}\p{Cs}]/u;
+
+/**
+ * Prepare text for printing: strip ANSI escape sequences, collapse horizontal
+ * whitespace runs to single spaces and newline-bearing runs to one
+ * {@link NEWLINE_GLYPH} (drawn as a pitch-black cell), then fold everything
+ * outside the fonts' ASCII + Latin-1 coverage to ASCII approximations.
+ * Unrenderable control/format/combining characters are dropped without
+ * occupying a cell; `?` remains the fallback for unsupported graphic
+ * characters. The zero-width ink toggles {@link DIM_ON}/{@link DIM_OFF} pass
+ * through untouched.
+ */
+export function normalize(text: string): string {
+	const stripped = text.includes("\u001b") ? Bun.stripANSI(text) : text;
+	const collapsed = stripped
+		// A run of pure format chars (BOM is both \s and Cf) vanishes; only a
+		// run containing genuine whitespace separates words.
+		.replace(COLLAPSIBLE, run => (LINE_BREAK.test(run) ? NEWLINE_GLYPH : /[^\p{Cf}]/u.test(run) ? " " : ""))
+		.replace(EDGE_RUNS, "");
+	let out = "";
+	for (const ch of collapsed) {
+		const cp = ch.codePointAt(0) as number;
+		if ((cp >= 0x20 && cp < 0x7f) || (cp >= 0xa0 && cp <= 0xff)) {
+			out += ch;
+			continue;
+		}
+		if (ch === DIM_ON || ch === DIM_OFF || ch === NEWLINE_GLYPH) {
+			out += ch;
+			continue;
+		}
+		const fold = CHAR_FOLD[ch];
+		if (fold !== undefined) {
+			out += fold;
+		} else if (cp >= 0x2500 && cp <= 0x257f) {
+			// Box drawing: keep table skeletons legible.
+			out += cp === 0x2502 || cp === 0x2503 ? "|" : cp === 0x2500 || cp === 0x2501 ? "-" : "+";
+		} else if (!UNRENDERABLE.test(ch)) {
+			out += "?";
+		}
+	}
+	return out;
+}
+
+// ============================================================================
+// Stopword dimming
+// ============================================================================
+
+/** High-frequency function words a reader can reconstruct from context; the
+ *  dim shapes render them in light gray so content words carry the contrast
+ *  (verbatim from `research/bdf.py` `_STOPWORDS`). */
+const STOPWORDS: ReadonlySet<string> = new Set(
+	(
+		"the a an and or of to in on at as is are was were be been by for with that this it its from had has have not but " +
+		"he she his her they their them which also who whom when where while will would could should there then than " +
+		"into over under about after before between during each such these those some most more other only same so"
+	).split(" "),
+);
+
+/** Maximal alphabetic runs (ASCII + Latin-1 letters, the fonts' coverage). */
+const ALPHA_RUN = /[a-zA-Z\u00c0-\u00d6\u00d8-\u00f6\u00f8-\u00ff]+/g;
+
+/** Splitter that keeps the zero-width ink toggles as their own segments. */
+const DIM_MARKER_SPLIT = /([\u000e\u000f])/;
+
+/**
+ * Wrap each maximal alphabetic run that is a stopword in {@link DIM_ON} /
+ * {@link DIM_OFF} so it prints in dim gray ink. Spans that are already dim
+ * (e.g. archived tool output) pass through untouched — wrapping there would
+ * terminate the enclosing dim span early. Markers are zero-width, so the
+ * visible glyph count is unchanged.
+ */
+export function dimStopwords(text: string): string {
+	const parts = text.split(DIM_MARKER_SPLIT);
+	let dim = false;
+	let out = "";
+	for (const part of parts) {
+		if (part === DIM_ON) {
+			dim = true;
+			out += part;
+		} else if (part === DIM_OFF) {
+			dim = false;
+			out += part;
+		} else if (dim) {
+			out += part;
+		} else {
+			out += part.replace(ALPHA_RUN, word => (STOPWORDS.has(word.toLowerCase()) ? DIM_ON + word + DIM_OFF : word));
+		}
+	}
+	return out;
+}
+
+// ============================================================================
+// Doc layout (two word-wrapped newspaper columns)
+// ============================================================================
+
+/** Char cells between the two doc columns (research exp14 `GUTTER`). */
+const DOC_GUTTER = 3;
+
+/**
+ * Greedy word-wrap, no mid-word breaks (hard split only for width+ words) —
+ * ported verbatim from `research/exp14_bestgpt.py` `wrap()`. Zero-width dim
+ * markers count toward word length here; serialized history places them at
+ * word boundaries, so the drift is at most one cell per affected line.
+ */
+export function wrap(text: string, width: number): string[] {
+	const lines: string[] = [];
+	let cur = "";
+	for (const token of text.split(/\s+/)) {
+		if (token.length === 0) continue;
+		let word = token;
+		while (word.length > width) {
+			// Pathological; never hit on prose.
+			if (cur) {
+				lines.push(cur);
+				cur = "";
+			}
+			lines.push(word.slice(0, width));
+			word = word.slice(width);
+		}
+		if (!cur) {
+			cur = word;
+		} else if (cur.length + 1 + word.length <= width) {
+			cur += ` ${word}`;
+		} else {
+			lines.push(cur);
+			cur = word;
+		}
+	}
+	if (cur) lines.push(cur);
+	return lines;
+}
+
+/**
+ * Paginate already-normalized text for a doc shape: wrap once at the column
+ * width, then slice into pages of `2 * rows` lines, each page `\n`-joined.
+ * Every input character lands on exactly one page (whitespace becomes the
+ * wrap points).
+ */
+function docPages(normalized: string, geo: Geometry): string[] {
+	const lines = wrap(normalized, geo.cols);
+	const perPage = 2 * geo.rows;
+	const pages: string[] = [];
+	for (let offset = 0; offset < lines.length; offset += perPage) {
+		pages.push(lines.slice(offset, offset + perPage).join("\n"));
+	}
+	return pages;
+}
+
+// ============================================================================
+// Rendering
+// ============================================================================
+
+export function geometry(shape: Shape, size: number = shape.frameSize): Geometry {
+	const gridCols = Math.floor(size / shape.cellWidth);
+	const rows = Math.floor(size / shape.cellHeight / shape.lineRepeat);
+	if (shape.columns === 2) {
+		const cols = Math.floor((gridCols - DOC_GUTTER) / 2);
+		return { cols, rows, capacity: 2 * cols * rows };
+	}
+	return { cols: gridCols, rows, capacity: gridCols * rows };
+}
+
+const NEWLINES = /\n/g;
+
+/** Render one snapcompact frame from already-normalized text. Doc shapes
+ *  (`columns === 2`) expect one page of `\n`-joined pre-wrapped lines. */
+export function render(text: string, shape: Shape, size: number = shape.frameSize): RenderedFrame {
+	const { cols, rows, capacity } = geometry(shape, size);
+	let visible = text.length - (text.match(DIM_MARKERS)?.length ?? 0);
+	// Doc line separators consume no cell; in the grid they print as a blank.
+	if (shape.columns === 2) visible -= text.match(NEWLINES)?.length ?? 0;
+	const chars = Math.min(visible, capacity);
+	const data = renderSnapcompactPng(text, {
+		size,
+		font: shape.font,
+		cellWidth: shape.cellWidth,
+		cellHeight: shape.cellHeight,
+		stretch: shape.stretch,
+		variant: shape.variant,
+		lineRepeat: shape.lineRepeat,
+		columns: shape.columns,
+	});
+	return { data, cols, rows, chars };
+}
+
+/** Stateful per-page text finisher: re-opens a dim span the previous page
+ *  boundary cut through, then applies stopword dimming when the shape asks
+ *  for it (after pagination, so capacity math never sees the markers). */
+function pageFinisher(shape: Shape): (page: string) => string {
+	let dimOpen = false;
+	return page => {
+		const text = dimOpen ? DIM_ON + page : page;
+		dimOpen = text.lastIndexOf(DIM_ON) > text.lastIndexOf(DIM_OFF);
+		return shape.stopwordDim ? dimStopwords(text) : text;
+	};
+}
+
+/** Options for {@link renderMany} and {@link frames}. */
+export interface RenderManyOptions {
+	/** Explicit shape; wins over `model`. */
+	shape?: Shape;
+	/** Model whose `api` selects the eval-optimal shape. */
+	model?: Pick<Model, "api">;
+	/** Frame edge in px; defaults to the shape's `frameSize`. */
+	frameSize?: number;
+	/** Hard cap on frames produced; omit for unbounded (caller decides usage). */
+	maxFrames?: number;
+}
+
+/**
+ * Render arbitrary text into snapcompact PNG frames as LLM image blocks
+ * (first page first). Synchronous: safe to call from per-request transforms.
+ * Empty/whitespace-only input yields no frames.
+ */
+export function renderMany(text: string, options?: RenderManyOptions): ImageContent[] {
+	const shape = options?.shape ?? resolveShape(options?.model);
+	const frameSize = options?.frameSize ?? shape.frameSize;
+	const geo = geometry(shape, frameSize);
+	const normalized = normalize(text);
+	const frames: ImageContent[] = [];
+	const push = (rendered: RenderedFrame): void => {
+		frames.push({
+			type: "image",
+			data: rendered.data,
+			mimeType: "image/png",
+			...(shape.imageDetail ? { detail: shape.imageDetail } : {}),
+		});
+	};
+	if (shape.columns === 2) {
+		const finish = pageFinisher(shape);
+		for (const page of docPages(normalized, geo)) {
+			if (options?.maxFrames !== undefined && frames.length >= options.maxFrames) break;
+			push(render(finish(page), shape, frameSize));
+		}
+		return frames;
+	}
+	for (let offset = 0; offset < normalized.length; offset += geo.capacity) {
+		if (options?.maxFrames !== undefined && frames.length >= options.maxFrames) break;
+		let chunk = normalized.slice(offset, offset + geo.capacity);
+		if (shape.stopwordDim) chunk = dimStopwords(chunk);
+		push(render(chunk, shape, frameSize));
+	}
+	return frames;
+}
+
+/** Frames needed to hold `text` at the given shape/size, without rendering.
+ *  For doc shapes this wraps the text once and counts pages of `2 * rows`
+ *  lines; for grid shapes it divides by the frame capacity. */
+export function frames(text: string, options?: Pick<RenderManyOptions, "shape" | "model" | "frameSize">): number {
+	const shape = options?.shape ?? resolveShape(options?.model);
+	const geo = geometry(shape, options?.frameSize ?? shape.frameSize);
+	const normalized = normalize(text);
+	if (shape.columns === 2) return Math.ceil(wrap(normalized, geo.cols).length / (2 * geo.rows));
+	return Math.ceil(normalized.length / geo.capacity);
+}
+
+// ============================================================================
+// Archive helpers
+// ============================================================================
+
+/** Validate and extract a persisted frame archive from `preserveData`. */
+export function getPreservedArchive(preserveData: Record<string, unknown> | undefined): Archive | undefined {
+	const candidate = preserveData?.[PRESERVE_KEY];
+	if (!candidate || typeof candidate !== "object") return undefined;
+	const archive = candidate as Archive;
+	if (!Array.isArray(archive.frames)) return undefined;
+	const frames = archive.frames.filter(
+		frame =>
+			!!frame &&
+			typeof frame.data === "string" &&
+			frame.data.length > 0 &&
+			typeof frame.mimeType === "string" &&
+			typeof frame.cols === "number" &&
+			typeof frame.rows === "number" &&
+			typeof frame.chars === "number",
+	);
+	if (frames.length === 0) return undefined;
+	return {
+		frames,
+		totalChars: typeof archive.totalChars === "number" ? archive.totalChars : 0,
+		truncatedChars: typeof archive.truncatedChars === "number" ? archive.truncatedChars : 0,
+		...(typeof archive.textTail === "string" && archive.textTail.length > 0 ? { textTail: archive.textTail } : {}),
+	};
+}
+
+/** Convert archive frames into LLM image blocks (oldest first). */
+export function images(archive: Archive): ImageContent[] {
+	return archive.frames.map(frame => ({
+		type: "image",
+		data: frame.data,
+		mimeType: frame.mimeType,
+		...(frame.detail ? { detail: frame.detail } : {}),
+	}));
+}
+
+// ============================================================================
+// Compaction entry point
+// ============================================================================
+
+/**
+ * Run a snapcompact compaction over prepared messages. Fully local: serializes
+ * the discarded history, prints it onto PNG frames in the provider-optimal
+ * shape, merges previously archived frames (oldest dropped beyond the
+ * budget), and produces a deterministic summary explaining how to read the
+ * frames. Pages past the frame budget are never rendered (providers with
+ * hard image caps silently drop excess frames on the wire) — the newest
+ * unrendered slice survives verbatim as a text tail on the summary and is
+ * folded back into frames by the next compaction.
+ *
+ * Frames archived under a different shape (provider switches, legacy 5x8
+ * sessions) are kept as-is — each frame carries its own geometry, and the
+ * summary describes the newest shape while noting that older frames may
+ * differ.
+ *
+ * If the previous compaction was text-based, its summary is printed at the
+ * head of the frame archive as `[Summary of earlier history]` so no continuity is lost.
+ */
+export async function compact<TMessage = Message>(
+	preparation: CompactionPreparation<TMessage>,
+	options?: Options<TMessage>,
+): Promise<CompactionResult> {
+	const { firstKeptEntryId, tokensBefore, previousSummary, previousPreserveData, fileOps } = preparation;
+	if (!firstKeptEntryId) {
+		throw new Error("First kept entry has no ID - session may need migration");
+	}
+	const shape = options?.shape ?? resolveShape(options?.model);
+	const frameSize = options?.frameSize ?? shape.frameSize;
+	const maxFrames = Math.max(1, options?.maxFrames ?? MAX_FRAMES);
+	const geo = geometry(shape, frameSize);
+
+	const messages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
+	const llmMessages = (options?.convertToLlm ?? defaultConvertToLlm)(messages);
+	let archiveText = normalize(serializeConversation(llmMessages, options));
+
+	const previousArchive = getPreservedArchive(previousPreserveData);
+	const includedPreviousSummary = !previousArchive && !!previousSummary;
+	if (includedPreviousSummary && previousSummary) {
+		const head = `[Summary of earlier history] ${normalize(previousSummary)}`;
+		archiveText = archiveText.length > 0 ? `${head} [Recent conversation] ${archiveText}` : head;
+	}
+
+	let truncatedChars = previousArchive?.truncatedChars ?? 0;
+
+	// The previous compaction's unframed text tail is the oldest part of this
+	// archive slice — prepend it so it ages into frames first.
+	if (previousArchive?.textTail) {
+		archiveText =
+			archiveText.length > 0
+				? `${previousArchive.textTail}${NEWLINE_GLYPH}${archiveText}`
+				: previousArchive.textTail;
+	}
+
+	const pages: string[] = [];
+	if (shape.columns === 2) {
+		pages.push(...docPages(archiveText, geo));
+	} else {
+		for (let offset = 0; offset < archiveText.length; offset += geo.capacity) {
+			pages.push(archiveText.slice(offset, offset + geo.capacity));
+		}
+	}
+
+	// Fit the merged archive into the frame budget BEFORE rendering: pages
+	// that cannot ship are never rasterized. Old unpinned frames evict first
+	// (the archive fades oldest-first, as before); new pages that still do
+	// not fit stay behind as a verbatim text tail instead of being dropped.
+	const prevFrames = previousArchive?.frames ?? [];
+	let keptPrev = prevFrames;
+	if (prevFrames.length + pages.length > maxFrames) {
+		// Pin the earliest frame: it anchors the session head (the original
+		// request, or the filmed summary of even older history) the way the
+		// LLM-summary strategies keep the original goal alive across rounds.
+		// With a budget of one frame the pin is moot.
+		const pinCount = maxFrames >= 2 && prevFrames.length > 0 ? 1 : 0;
+		const evictable = prevFrames.slice(pinCount);
+		const surviving = Math.min(evictable.length, Math.max(0, maxFrames - pages.length - pinCount));
+		const dropped = evictable.slice(0, evictable.length - surviving);
+		for (const frame of dropped) truncatedChars += frame.chars;
+		keptPrev = [...prevFrames.slice(0, pinCount), ...evictable.slice(evictable.length - surviving)];
+	}
+	const renderPages = pages.slice(0, maxFrames - keptPrev.length);
+	const tailPages = pages.slice(renderPages.length);
+
+	const newFrames: Frame[] = [];
+	const finish = pageFinisher(shape);
+	for (const page of renderPages) {
+		const rendered = render(finish(page), shape, frameSize);
+		newFrames.push({
+			data: rendered.data,
+			mimeType: "image/png",
+			cols: rendered.cols,
+			rows: rendered.rows,
+			chars: rendered.chars,
+			font: shape.font,
+			variant: shape.variant,
+			lineRepeat: shape.lineRepeat,
+			...(shape.columns === 2 ? { columns: 2 } : {}),
+			...(shape.stopwordDim ? { stopwordDim: true } : {}),
+			...(shape.imageDetail ? { detail: shape.imageDetail } : {}),
+		});
+		// Keep the event loop responsive between native render passes.
+		await Bun.sleep(0);
+	}
+
+	// Pages past the budget survive as text, capped at two frames' capacity
+	// (middle-elided) so an oversized archive cannot blow the context back up.
+	let textTail = "";
+	if (tailPages.length > 0) {
+		const raw =
+			shape.columns === 2 ? tailPages.map(page => page.replaceAll("\n", " ")).join(" ") : tailPages.join("");
+		const tailCap = TEXT_TAIL_MAX_PAGES * geo.capacity;
+		if (raw.length > tailCap) truncatedChars += raw.length - tailCap;
+		// Re-open a dim span the render boundary cut through, so the carried
+		// tail keeps tool output dim when it lands on frames next compaction.
+		const renderedText = shape.columns === 2 ? renderPages.join("\n") : renderPages.join("");
+		const dimOpen = renderedText.lastIndexOf(DIM_ON) > renderedText.lastIndexOf(DIM_OFF);
+		textTail = (dimOpen ? DIM_ON : "") + truncateForSummary(raw, tailCap, TRUNCATE_HEAD_RATIO);
+	}
+
+	const frames = [...keptPrev, ...newFrames];
+	const totalChars = frames.reduce((sum, frame) => sum + frame.chars, 0);
+	const mixedShapes = frames.some(
+		frame =>
+			frame.cols !== geo.cols ||
+			frame.rows !== geo.rows ||
+			(frame.variant ?? "sent") !== shape.variant ||
+			(frame.lineRepeat ?? 1) !== shape.lineRepeat ||
+			(frame.columns ?? 1) !== (shape.columns ?? 1) ||
+			(frame.stopwordDim ?? false) !== (shape.stopwordDim ?? false),
+	);
+
+	let summary: string;
+	if (frames.length === 0) {
+		summary = "No prior history.";
+	} else {
+		summary = prompt.render(snapcompactSummaryPrompt, {
+			frameCount: frames.length,
+			multipleFrames: frames.length > 1,
+			fontCell: `${shape.cellWidth}x${shape.cellHeight}`,
+			cols: geo.cols,
+			rows: geo.rows,
+			sentenceInk: shape.variant === "sent",
+			lineRepeated: shape.lineRepeat > 1,
+			docColumns: shape.columns === 2,
+			stopwordDimmed: shape.stopwordDim === true,
+			dimmedToolResults: options?.dimToolResults !== false,
+			mixedShapes,
+			totalChars,
+			truncatedChars,
+			includedPreviousSummary,
+			textTail: textTail.length > 0 ? toPlainText(textTail) : undefined,
+		});
+	}
+	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+	summary = upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
+
+	// A snapcompact pass replaces any provider-side replacement history; strip the
+	// OpenAI remote-compaction payload like the default summarizer path does.
+	const basePreserve = stripOpenAiRemoteCompactionPreserveData(previousPreserveData) ?? {};
+	const archive: Archive = { frames, totalChars, truncatedChars, ...(textTail ? { textTail } : {}) };
+
+	const textTailNote = textTail ? ` (+${textTail.length.toLocaleString()} chars as text)` : "";
+	return {
+		summary,
+		shortSummary: `Archived ${totalChars.toLocaleString()} chars of history onto ${frames.length} snapcompact frame${frames.length === 1 ? "" : "s"}${textTailNote}`,
+		firstKeptEntryId,
+		tokensBefore,
+		details: { readFiles, modifiedFiles },
+		preserveData: { ...basePreserve, [PRESERVE_KEY]: archive },
+	};
+}