@oh-my-pi/snapcompact 18.15.0 → 18.16.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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

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,24 @@ 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}). */
@@ -687,13 +704,15 @@ export interface ViewWithoutFramesOptions {
  * 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. With
+ * 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. An archive with no frames, no reasoning to drop and no
- * text past `maxChars` is returned as is.
+ * 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;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/snapcompact",
-	"version": "18.15.0",
+	"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.15.0",
-		"@oh-my-pi/pi-catalog": "18.15.0",
-		"@oh-my-pi/pi-natives": "18.15.0",
-		"@oh-my-pi/pi-utils": "18.15.0",
-		"@oh-my-pi/pi-wire": "18.15.0"
+		"@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,7 +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: keep FILES_SECTION_HEAD and HISTORY_SECTION_HEAD in step with these headings. --}}
+{{!-- 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,
@@ -2335,6 +2347,19 @@ 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);
@@ -2381,22 +2406,31 @@ function keepEnds(archive: Archive, maxChars: number): Archive {
  * 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. With
+ * 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. An archive with no frames, no reasoning to drop and no
- * text past `maxChars` is returned as is.
+ * 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 dropThinking = options.includeThinking === false && summaryIncludesThinking(summary);
+	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) return { summary, archive };
+	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) {
@@ -2409,12 +2443,7 @@ export function viewWithoutFrames(
 			textHead: text,
 		};
 	} else {
-		// Without the whole source the tail may open inside a section cut off in
-		// the dropped middle, whose scope is unknown; a reader without reasoning
-		// skips those lines (see sourceForReaderWithoutThinking).
-		const tail = archive.textTail ?? "";
-		const labelled = dropThinking ? tail.search(SECTION_START) : 0;
-		const keptTail = labelled < 0 ? "" : tail.slice(labelled);
+		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);
@@ -2429,13 +2458,17 @@ export function viewWithoutFrames(
 	if (options.maxChars !== undefined) textArchive = keepEnds(textArchive, Math.max(0, Math.floor(options.maxChars)));
 	const source = textArchive.text ?? textArchive.textHead ?? "";
 	return {
-		summary: prompt.render(snapcompactSummaryPrompt, {
-			frameCount: 0,
-			truncatedChars: textArchive.truncatedChars,
-			includedPreviousSummary: source.startsWith(PREVIOUS_SUMMARY_HEAD),
-			files: summaryFileSection(summary),
-			includeThinking: summaryIncludesThinking(summary) && !dropThinking,
-		}),
+		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,
 	};
 }