@oh-my-pi/snapcompact 18.14.2 → 18.16.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.16.0] - 2026-11-02
+
+### Added
+
+- Added `archiveIncludesThinking()`, whether a compaction may replay reasoning from its summary's legend or its archive's text, and `viewSummary()`, which keeps a summary the template did not write in its own words, followed by the template's guide to the view's text ([#17745](https://github.com/can1357/oh-my-pi/pull/17745) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed `viewWithoutFrames` and `viewWithoutThinking` keeping an archive's reasoning for a reader without it when the summary (say, one an extension wrote) declares no `¶think:` scope, and replacing such a summary with the template's ([#17745](https://github.com/can1357/oh-my-pi/pull/17745) by [@will-bogusz](https://github.com/will-bogusz))
+
+## [18.15.0] - 2026-11-01
+
+### Added
+
+- Added `viewWithoutFrames`: what a reader without image input reads for an archive, its kept text in place of its frames ([#17510](https://github.com/can1357/oh-my-pi/pull/17510) by [@will-bogusz](https://github.com/will-bogusz))
+
 ## [18.13.3] - 2026-10-28
 
 ### Changed

package/dist/types/snapcompact.d.ts

@@ -661,6 +661,13 @@ export declare function readerIncludesThinking(model: Model): boolean;
  *  archives rendered with {@link SerializeOptions.includeThinking}, and for
  *  summaries written before that legend was gated on it. */
 export declare function summaryIncludesThinking(summary: string): boolean;
+/**
+ * Whether a compaction whose summary is `summary` and archive `archive` may
+ * replay assistant reasoning: its summary declares `¶think:` scopes, or its
+ * kept text carries a `¶think:` section. A summary an extension or custom
+ * template wrote need not carry the legend while its archive's source does.
+ */
+export declare function archiveIncludesThinking(summary: string, archive: Archive): boolean;
 /** `text` (a summary or archive source, raw or normalized) without its
  *  `¶think:` sections, and with the reasoning scope dropped from any legend. */
 export declare function textWithoutThinking(text: string): string;
@@ -668,14 +675,46 @@ export declare function textWithoutThinking(text: string): string;
  * What a reader that excludes assistant reasoning reads for a compaction
  * whose summary is `summary` and archive `archive`: the archive's
  * {@link Archive.withoutThinking} variant when it carries one, the original
- * when its summary declares no reasoning, else a fail-closed text-only form.
+ * when it carries no reasoning ({@link archiveIncludesThinking}), else a
+ * fail-closed text-only form.
  * That form keeps no frames (pixels cannot be scrubbed), takes its text edges
  * from the source after every `¶think:` section is removed (so a section
  * crossing an edge cannot leak), counts the dropped middle as truncated, and
  * re-renders the summary without the reasoning legend; `details` restores its
- * file list.
+ * file list. A summary the template did not write keeps its own words
+ * ({@link viewSummary}).
  */
 export declare function viewWithoutThinking(summary: string, archive: Archive, details?: CompactionDetails): ArchiveView;
+/**
+ * The summary a reader reads with an archive view: `rendered`, the template's
+ * summary for that view, when `summary` came from the template; otherwise
+ * `summary`'s own words (say, an extension's), without reasoning when
+ * `dropThinking`, followed by `rendered`, so the facts it alone holds survive
+ * the swap and the reader still gets the guide to the view's text.
+ */
+export declare function viewSummary(summary: string, rendered: string, dropThinking: boolean): string;
+/** Options for {@link viewWithoutFrames}. */
+export interface ViewWithoutFramesOptions {
+    /** `false` for a reader that excludes assistant reasoning ({@link readerIncludesThinking}). */
+    includeThinking?: boolean;
+    /** Most archive characters the reader takes; the middle past it is dropped, both ends kept. */
+    maxChars?: number;
+}
+/**
+ * What a reader without image input reads for a compaction whose summary is
+ * `summary` and archive `archive`: the archive's kept source
+ * ({@link Archive.text}) as plain text in place of its frames, and the summary
+ * re-rendered without the frame legend, its file list kept (one the template
+ * did not write keeps its own words, {@link viewSummary}). With
+ * `includeThinking: false` the text and legend also leave out reasoning, as
+ * {@link viewWithoutThinking} does, without rendering frames this reader
+ * cannot see; past `maxChars` the middle of the text is dropped. An archive
+ * persisted without that source keeps its text edges and counts the imaged
+ * middle as dropped; a reader without reasoning also skips the tail's lines
+ * before its first scope label, whatever the summary declares. An archive with
+ * no frames, no reasoning to drop and no text past `maxChars` is returned as is.
+ */
+export declare function viewWithoutFrames(summary: string, archive: Archive, options?: ViewWithoutFramesOptions): ArchiveView;
 /**
  * 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": "18.14.2",
+	"version": "18.16.0",
 	"description": "Bitmap-frame context compression for vision-capable LLMs",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -34,11 +34,12 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.14.2",
-		"@oh-my-pi/pi-catalog": "18.14.2",
-		"@oh-my-pi/pi-natives": "18.14.2",
-		"@oh-my-pi/pi-utils": "18.14.2",
-		"@oh-my-pi/pi-wire": "18.14.2"
+		"@oh-my-pi/omptype": "18.16.0",
+		"@oh-my-pi/pi-ai": "18.16.0",
+		"@oh-my-pi/pi-catalog": "18.16.0",
+		"@oh-my-pi/pi-natives": "18.16.0",
+		"@oh-my-pi/pi-utils": "18.16.0",
+		"@oh-my-pi/pi-wire": "18.16.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/prompts/snapcompact-summary.md

@@ -19,6 +19,7 @@ Reading HISTORY:
 {{/if}}{{#if truncatedChars}}- About {{truncatedChars}} characters of older middle history dropped to fit archive budget.
 {{/if}}- If an exact earlier detail matters and a section is unclear, re-derive from workspace (re-read files, re-run commands), rather than guess.
 
+{{!-- viewWithoutFrames (snapcompact.ts) reads this FILES section back out of a rendered summary, and viewSummary tells this template's summaries from others by their closing HISTORY heading: keep FILES_SECTION_HEAD and HISTORY_SECTION_HEAD in step with these headings. --}}
 {{#if files}}FILES
 ===================
 {{files}}

package/src/snapcompact.ts

@@ -53,6 +53,7 @@
  * re-attached to the compaction summary message on every context rebuild.
  */
 
+import { type } from "@oh-my-pi/omptype";
 import type { Api, ImageContent, Message, Model, TextContent } from "@oh-my-pi/pi-ai";
 import { reachesBudgetedHost } from "@oh-my-pi/pi-ai/providers/anthropic-state";
 import { resolveCatalogPolicy } from "@oh-my-pi/pi-catalog/compat/catalog-policy";
@@ -320,32 +321,25 @@ export const SHAPES = {
 	legacy: priceShape(SHAPE_VARIANTS["5x8-sent"], { api: "anthropic-messages" }),
 } satisfies Record<string, Shape>;
 
+/** In-memory shapes may carry optional keys as `undefined`. */
+const ShapeSchema = type({
+	font: "'5x8' | '8x8' | '6x12' | '8x13' | 'silver'",
+	cellWidth: "number > 0",
+	cellHeight: "number > 0",
+	"stretch?": "boolean | undefined",
+	variant: "'sent' | 'bw'",
+	"stopwordDim?": "boolean | undefined",
+	"columns?": "1 | 2 | undefined",
+	lineRepeat: "number > 0",
+	frameSize: "number > 0",
+	frameTokenEstimate: "number > 0",
+	"frameTokensVerified?": "boolean | undefined",
+	"imageDetail?": "'auto' | 'low' | 'high' | 'original' | undefined",
+});
+
 /** 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" || font === "silver") &&
-		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 &&
-		(shape.frameTokensVerified === undefined || typeof shape.frameTokensVerified === "boolean") &&
-		(detail === undefined || detail === "auto" || detail === "low" || detail === "high" || detail === "original")
-	);
+	return ShapeSchema.allows(value);
 }
 
 /** Eval-winning variant per wire family (fallback when the model id matches
@@ -2259,6 +2253,19 @@ export function summaryIncludesThinking(summary: string): boolean {
 	return summary.includes(THINK_LABEL);
 }
 
+/**
+ * Whether a compaction whose summary is `summary` and archive `archive` may
+ * replay assistant reasoning: its summary declares `¶think:` scopes, or its
+ * kept text carries a `¶think:` section. A summary an extension or custom
+ * template wrote need not carry the legend while its archive's source does.
+ */
+export function archiveIncludesThinking(summary: string, archive: Archive): boolean {
+	if (summaryIncludesThinking(summary)) return true;
+	return [archive.text ?? archive.textHead, archive.text === undefined ? archive.textTail : undefined].some(
+		text => text?.includes(THINK_LABEL) === true && stripThinkingSections(text) !== text,
+	);
+}
+
 /** The reasoning scope in a scope legend, current and earlier summary wordings
  *  alike, wherever it sits: a summary, or one archived inside another archive. */
 const LEGEND_REASONING_SCOPE =
@@ -2291,16 +2298,18 @@ function sourceForReaderWithoutThinking(archive: Archive): string {
  * What a reader that excludes assistant reasoning reads for a compaction
  * whose summary is `summary` and archive `archive`: the archive's
  * {@link Archive.withoutThinking} variant when it carries one, the original
- * when its summary declares no reasoning, else a fail-closed text-only form.
+ * when it carries no reasoning ({@link archiveIncludesThinking}), else a
+ * fail-closed text-only form.
  * That form keeps no frames (pixels cannot be scrubbed), takes its text edges
  * from the source after every `¶think:` section is removed (so a section
  * crossing an edge cannot leak), counts the dropped middle as truncated, and
  * re-renders the summary without the reasoning legend; `details` restores its
- * file list.
+ * file list. A summary the template did not write keeps its own words
+ * ({@link viewSummary}).
  */
 export function viewWithoutThinking(summary: string, archive: Archive, details?: CompactionDetails): ArchiveView {
 	if (archive.withoutThinking) return archive.withoutThinking;
-	if (!summaryIncludesThinking(summary)) return { summary, archive };
+	if (!archiveIncludesThinking(summary, archive)) return { summary, archive };
 	const source = sourceForReaderWithoutThinking(archive);
 	const text = textWithoutThinking(source);
 	const headChars = archive.textHead?.length ?? 0;
@@ -2311,7 +2320,8 @@ export function viewWithoutThinking(summary: string, archive: Archive, details?:
 	const truncatedChars = archive.truncatedChars + (fits ? 0 : text.length - headChars - tailChars);
 	const files = details ? formatFileList(details.readFiles, details.modifiedFiles) : "";
 	return {
-		summary:
+		summary: viewSummary(
+			summary,
 			textHead.length === 0 && files.length === 0
 				? "No prior history."
 				: prompt.render(snapcompactSummaryPrompt, {
@@ -2321,6 +2331,8 @@ export function viewWithoutThinking(summary: string, archive: Archive, details?:
 						files: files.length > 0 ? files : undefined,
 						includeThinking: false,
 					}),
+			true,
+		),
 		archive: {
 			frames: [],
 			totalChars: textHead.length + textTail.length,
@@ -2332,6 +2344,135 @@ export function viewWithoutThinking(summary: string, archive: Archive, details?:
 	};
 }
 
+const FILES_SECTION_HEAD = "FILES\n===================\n";
+const HISTORY_SECTION_HEAD = "HISTORY\n===================";
+
+/**
+ * The summary a reader reads with an archive view: `rendered`, the template's
+ * summary for that view, when `summary` came from the template; otherwise
+ * `summary`'s own words (say, an extension's), without reasoning when
+ * `dropThinking`, followed by `rendered`, so the facts it alone holds survive
+ * the swap and the reader still gets the guide to the view's text.
+ */
+export function viewSummary(summary: string, rendered: string, dropThinking: boolean): string {
+	if (summary.trimEnd().endsWith(HISTORY_SECTION_HEAD)) return rendered;
+	const own = (dropThinking ? textWithoutThinking(summary) : summary).trim();
+	return own.length > 0 ? `${own}\n\n${rendered}` : rendered;
+}
+
+/** The FILES section of a snapcompact summary as it was rendered, or `undefined` when it lists none. */
+function summaryFileSection(summary: string): string | undefined {
+	const start = summary.indexOf(FILES_SECTION_HEAD);
+	const end = summary.lastIndexOf(HISTORY_SECTION_HEAD);
+	if (start < 0 || end < start) return undefined;
+	const files = summary.slice(start + FILES_SECTION_HEAD.length, end).replace(TRAILING_LINE_BREAKS, "");
+	return files.length > 0 ? files : undefined;
+}
+
+/** Options for {@link viewWithoutFrames}. */
+export interface ViewWithoutFramesOptions {
+	/** `false` for a reader that excludes assistant reasoning ({@link readerIncludesThinking}). */
+	includeThinking?: boolean;
+	/** Most archive characters the reader takes; the middle past it is dropped, both ends kept. */
+	maxChars?: number;
+}
+
+/** `archive`'s text regions cut to `maxChars`, keeping both ends and counting the cut middle as dropped. */
+function keepEnds(archive: Archive, maxChars: number): Archive {
+	if (archive.totalChars <= maxChars) return archive;
+	let head = archive.textHead ?? "";
+	let tail = archive.textTail ?? "";
+	if (tail.length === 0) {
+		const headChars = Math.ceil(maxChars / 2);
+		tail = head.slice(head.length - (maxChars - headChars));
+		head = head.slice(0, headChars);
+	} else {
+		const headChars = Math.min(head.length, Math.max(Math.ceil(maxChars / 2), maxChars - tail.length));
+		const tailChars = Math.min(tail.length, maxChars - headChars);
+		head = head.slice(0, headChars);
+		tail = tail.slice(tail.length - tailChars);
+	}
+	const { textHead: _head, textTail: _tail, ...rest } = archive;
+	return {
+		...rest,
+		totalChars: head.length + tail.length,
+		truncatedChars: archive.truncatedChars + archive.totalChars - head.length - tail.length,
+		...(head ? { textHead: head } : {}),
+		...(tail ? { textTail: tail } : {}),
+	};
+}
+
+/**
+ * What a reader without image input reads for a compaction whose summary is
+ * `summary` and archive `archive`: the archive's kept source
+ * ({@link Archive.text}) as plain text in place of its frames, and the summary
+ * re-rendered without the frame legend, its file list kept (one the template
+ * did not write keeps its own words, {@link viewSummary}). With
+ * `includeThinking: false` the text and legend also leave out reasoning, as
+ * {@link viewWithoutThinking} does, without rendering frames this reader
+ * cannot see; past `maxChars` the middle of the text is dropped. An archive
+ * persisted without that source keeps its text edges and counts the imaged
+ * middle as dropped; a reader without reasoning also skips the tail's lines
+ * before its first scope label, whatever the summary declares. An archive with
+ * no frames, no reasoning to drop and no text past `maxChars` is returned as is.
+ */
+export function viewWithoutFrames(
+	summary: string,
+	archive: Archive,
+	options: ViewWithoutFramesOptions = {},
+): ArchiveView {
+	const excludeThinking = options.includeThinking === false;
+	const dropThinking = excludeThinking && archiveIncludesThinking(summary, archive);
+	// Without the whole source the tail may open inside a section cut off in the
+	// dropped middle, whose scope is unknown (it may be reasoning even when no
+	// edge shows a label); a reader without reasoning skips those lines (see
+	// sourceForReaderWithoutThinking).
+	const tail = archive.text ? "" : (archive.textTail ?? "");
+	const tailStart = excludeThinking && tail ? tail.search(SECTION_START) : 0;
+	const fits = options.maxChars === undefined || archive.totalChars <= options.maxChars;
+	if (archive.frames.length === 0 && !dropThinking && fits && tailStart === 0) return { summary, archive };
+	const scrub = (text: string): string => (dropThinking ? textWithoutThinking(text) : text);
+	let textArchive: Archive;
+	if (archive.text) {
+		const text = scrub(archive.text);
+		textArchive = {
+			frames: [],
+			totalChars: text.length,
+			truncatedChars: archive.truncatedChars,
+			text,
+			textHead: text,
+		};
+	} else {
+		const keptTail = tailStart < 0 ? "" : tail.slice(tailStart);
+		const textHead = scrub(archive.textHead ?? "");
+		const textTail = scrub(keptTail);
+		const framedChars = archive.frames.reduce((sum, frame) => sum + frame.chars, 0);
+		textArchive = {
+			frames: [],
+			totalChars: textHead.length + textTail.length,
+			truncatedChars: archive.truncatedChars + framedChars + tail.length - keptTail.length,
+			...(textHead ? { textHead } : {}),
+			...(textTail ? { textTail } : {}),
+		};
+	}
+	if (options.maxChars !== undefined) textArchive = keepEnds(textArchive, Math.max(0, Math.floor(options.maxChars)));
+	const source = textArchive.text ?? textArchive.textHead ?? "";
+	return {
+		summary: viewSummary(
+			summary,
+			prompt.render(snapcompactSummaryPrompt, {
+				frameCount: 0,
+				truncatedChars: textArchive.truncatedChars,
+				includedPreviousSummary: source.startsWith(PREVIOUS_SUMMARY_HEAD),
+				files: summaryFileSection(summary),
+				includeThinking: summaryIncludesThinking(summary) && !dropThinking,
+			}),
+			dropThinking,
+		),
+		archive: textArchive,
+	};
+}
+
 /**
  * Run a snapcompact compaction over prepared messages. Fully local: serializes
  * the discarded history, appends it to the accumulated archive source text, and