@oh-my-pi/snapcompact 16.2.7 → 16.2.8

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.2.8] - 2026-06-30
+
+### Fixed
+
+- Fixed large snapcompact archives being reconstructed into unbounded per-request image payloads by adding a frame base64 byte budget and omitting over-budget archive frames from prompt blocks. ([#3792](https://github.com/can1357/oh-my-pi/issues/3792))
+
 ## [16.2.7] - 2026-06-30
 
 ### Added

package/dist/types/snapcompact.d.ts

@@ -317,6 +317,21 @@ export declare const HQ_EDGE_FRAMES = 3;
  *  cap, billed at +5% margin (ceil(4784 * 1.05)). Keeps the overflow guard from
  *  undercounting a high-res archive at the raised {@link MAX_FRAMES_DEFAULT}. */
 export declare const FRAME_TOKEN_ESTIMATE = 5024;
+/** Conservative upper bound for one persisted frame's base64 payload. The
+ *  measured high-res Anthropic `8x13`/`11on16` PNG frames sit around 159 KB;
+ *  170 KB leaves margin for denser glyph pages without permitting multi-MB
+ *  standing request bodies at large context windows. */
+export declare const FRAME_DATA_BYTES_ESTIMATE = 170000;
+/** Maximum snapcompact image base64 carried in every rebuilt provider request.
+ *  Above this, provider backends can accept the HTTP body but fail mid-stream
+ *  with opaque 5xx errors. Keep this independent from visual-token budgeting:
+ *  a 1M-token model can afford 70 images on paper, but not the resulting
+ *  ~11 MB JSON payload on every turn. */
+export declare const FRAME_DATA_BYTES_BUDGET = 3000000;
+/** Frame-count cap implied by {@link FRAME_DATA_BYTES_BUDGET}. */
+export declare function maxFramesForDataBudget(maxFrameDataBytes?: number): number;
+/** Base64 byte length for persisted snapcompact frames. */
+export declare function frameDataBytes(frames: readonly Pick<Frame, "data">[]): number;
 /**
  * Per-request image-count budgets by provider id. These cap how many images an
  * entire request may carry (archive/system-prompt/tool-result imaging combined).
@@ -543,13 +558,18 @@ export declare function stripPreservedArchive(preserveData: Record<string, unkno
 export declare function archiveSourceText(archive: Archive): string | undefined;
 /** Build the text used to choose and preflight a font-aware snapcompact shape. */
 export declare function renderabilityProbeText(serialized: string, previousPreserveData?: Record<string, unknown>, previousSummary?: string): string;
+/** Options for reconstructing a persisted snapcompact archive into prompt blocks. */
+export interface HistoryBlockOptions {
+    /** Hard cap on image base64 bytes attached to one rebuilt provider request. */
+    maxFrameDataBytes?: number;
+}
 /** Convert archive frames into LLM image blocks (oldest first). */
 export declare function images(archive: Archive): ImageContent[];
 /** Ordered archive blocks for a compaction summary message, oldest to newest:
  *  the oldest text region, the imaged middle, then the newest text region.
  *  Runtime-only; reconstructed from {@link Archive} on each context rebuild
  *  instead of persisted on the session entry. */
-export declare function historyBlocks(archive: Archive): (TextContent | ImageContent)[];
+export declare function historyBlocks(archive: Archive, options?: HistoryBlockOptions): (TextContent | ImageContent)[];
 /**
  * Run a snapcompact compaction over prepared messages. Fully local: serializes
  * the discarded history, appends it to the accumulated archive source text, and

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/snapcompact",
-	"version": "16.2.7",
+	"version": "16.2.8",
 	"description": "Bitmap-frame context compression for vision-capable LLMs",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,10 +31,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.2.7",
-		"@oh-my-pi/pi-natives": "16.2.7",
-		"@oh-my-pi/pi-utils": "16.2.7",
-		"@oh-my-pi/pi-wire": "16.2.7"
+		"@oh-my-pi/pi-ai": "16.2.8",
+		"@oh-my-pi/pi-natives": "16.2.8",
+		"@oh-my-pi/pi-utils": "16.2.8",
+		"@oh-my-pi/pi-wire": "16.2.8"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/snapcompact.ts

@@ -424,6 +424,29 @@ export const HQ_EDGE_FRAMES = 3;
  *  undercounting a high-res archive at the raised {@link MAX_FRAMES_DEFAULT}. */
 export const FRAME_TOKEN_ESTIMATE = 5024;
 
+/** Conservative upper bound for one persisted frame's base64 payload. The
+ *  measured high-res Anthropic `8x13`/`11on16` PNG frames sit around 159 KB;
+ *  170 KB leaves margin for denser glyph pages without permitting multi-MB
+ *  standing request bodies at large context windows. */
+export const FRAME_DATA_BYTES_ESTIMATE = 170_000;
+
+/** Maximum snapcompact image base64 carried in every rebuilt provider request.
+ *  Above this, provider backends can accept the HTTP body but fail mid-stream
+ *  with opaque 5xx errors. Keep this independent from visual-token budgeting:
+ *  a 1M-token model can afford 70 images on paper, but not the resulting
+ *  ~11 MB JSON payload on every turn. */
+export const FRAME_DATA_BYTES_BUDGET = 3_000_000;
+
+/** Frame-count cap implied by {@link FRAME_DATA_BYTES_BUDGET}. */
+export function maxFramesForDataBudget(maxFrameDataBytes: number = FRAME_DATA_BYTES_BUDGET): number {
+	return Math.max(1, Math.floor(maxFrameDataBytes / FRAME_DATA_BYTES_ESTIMATE));
+}
+
+/** Base64 byte length for persisted snapcompact frames. */
+export function frameDataBytes(frames: readonly Pick<Frame, "data">[]): number {
+	return frames.reduce((sum, frame) => sum + frame.data.length, 0);
+}
+
 /**
  * Per-request image-count budgets by provider id. These cap how many images an
  * entire request may carry (archive/system-prompt/tool-result imaging combined).
@@ -1542,6 +1565,54 @@ export function renderabilityProbeText(
 	return serialized;
 }
 
+/** Options for reconstructing a persisted snapcompact archive into prompt blocks. */
+export interface HistoryBlockOptions {
+	/** Hard cap on image base64 bytes attached to one rebuilt provider request. */
+	maxFrameDataBytes?: number;
+}
+
+function formatFrameDataBytes(bytes: number): string {
+	if (bytes >= 1_000_000) return `${(bytes / 1_000_000).toFixed(1)} MB`;
+	if (bytes >= 1_000) return `${(bytes / 1_000).toFixed(1)} KB`;
+	return `${bytes} B`;
+}
+
+function imagesWithinBudget(
+	archive: Archive,
+	maxFrameDataBytes: number | undefined,
+): { images: ImageContent[]; omittedFrames: number; omittedBytes: number } {
+	if (maxFrameDataBytes === undefined) {
+		return { images: images(archive), omittedFrames: 0, omittedBytes: 0 };
+	}
+
+	let usedBytes = 0;
+	let omittedFrames = 0;
+	let omittedBytes = 0;
+	const keptNewestFirst: Frame[] = [];
+	for (let index = archive.frames.length - 1; index >= 0; index--) {
+		const frame = archive.frames[index];
+		if (!frame) continue;
+		const bytes = frame.data.length;
+		if (usedBytes + bytes > maxFrameDataBytes) {
+			omittedFrames++;
+			omittedBytes += bytes;
+			continue;
+		}
+		usedBytes += bytes;
+		keptNewestFirst.push(frame);
+	}
+	keptNewestFirst.reverse();
+	return { images: images({ ...archive, frames: keptNewestFirst }), omittedFrames, omittedBytes };
+}
+
+function omittedFrameNotice(omittedFrames: number, omittedBytes: number): string {
+	return [
+		"-------------- snapcompact image middle omitted",
+		`${omittedFrames.toLocaleString()} archived image frame${omittedFrames === 1 ? "" : "s"} (${formatFrameDataBytes(omittedBytes)} base64) exceeded the per-request snapcompact payload budget. The compacted summary and visible text edges remain available.`,
+		"--------------",
+	].join("\n");
+}
+
 /** Convert archive frames into LLM image blocks (oldest first). */
 export function images(archive: Archive): ImageContent[] {
 	return archive.frames.map(frame => ({
@@ -1555,23 +1626,38 @@ export function images(archive: Archive): ImageContent[] {
  *  the oldest text region, the imaged middle, then the newest text region.
  *  Runtime-only; reconstructed from {@link Archive} on each context rebuild
  *  instead of persisted on the session entry. */
-export function historyBlocks(archive: Archive): (TextContent | ImageContent)[] {
+export function historyBlocks(archive: Archive, options: HistoryBlockOptions = {}): (TextContent | ImageContent)[] {
 	const blocks: (TextContent | ImageContent)[] = [];
-	const hasImages = archive.frames.length > 0;
+	const budgeted = imagesWithinBudget(archive, options.maxFrameDataBytes);
+	const hasImages = budgeted.images.length > 0;
+	const hasOmittedImages = budgeted.omittedFrames > 0;
 	if (archive.textHead) {
-		const suffix = hasImages ? "\n-------------- imaged middle below\n" : "";
+		const suffix = hasImages
+			? "\n-------------- imaged middle below\n"
+			: hasOmittedImages
+				? `\n${omittedFrameNotice(budgeted.omittedFrames, budgeted.omittedBytes)}\n`
+				: "";
 		blocks.push({ type: "text", text: toPlainText(archive.textHead) + suffix });
+	} else if (hasOmittedImages && !hasImages) {
+		blocks.push({ type: "text", text: omittedFrameNotice(budgeted.omittedFrames, budgeted.omittedBytes) });
+	}
+	// Omitted frames are the OLDEST archived images: the byte budget keeps the
+	// newest tail frames, so the gap notice precedes the kept images to keep the
+	// reconstructed blocks oldest-to-newest.
+	if (hasImages && hasOmittedImages) {
+		blocks.push({ type: "text", text: omittedFrameNotice(budgeted.omittedFrames, budgeted.omittedBytes) });
 	}
-	blocks.push(...images(archive));
+	blocks.push(...budgeted.images);
 	if (archive.textTail) {
 		const prefix = hasImages
 			? "-------------- imaged middle above\n"
-			: archive.truncatedChars > 0
+			: archive.truncatedChars > 0 || hasOmittedImages
 				? "\n-------------- middle history omitted above\n"
 				: "";
 		const tail = prefix + toPlainText(archive.textTail);
-		if (blocks.length > 0 && blocks[blocks.length - 1]?.type === "text") {
-			(blocks[blocks.length - 1] as TextContent).text += tail;
+		const lastBlock = blocks[blocks.length - 1];
+		if (lastBlock?.type === "text") {
+			lastBlock.text += tail;
 		} else {
 			blocks.push({ type: "text", text: tail });
 		}