@oh-my-pi/pi-agent-core 18.6.1 → 18.7.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [18.7.0] - 2026-10-06
+
+### Fixed
+
+- Fixed interrupted runs so assistant message boundaries are emitted reliably, allowing subscribers to persist and recover the interrupted turn.
+
+## [18.6.3] - 2026-10-06
+
+### Breaking Changes
+
+- `Agent.withdrawUndeliveredQueuedMessages()` replaces `withdrawLiveSteering()` and returns `{ steering, followUp }`: it also takes back queued input already dequeued for the next model call, which the aborted run then neither records nor reports in `agent_end` ([#14179](https://github.com/can1357/oh-my-pi/pull/14179) by [@andrebrait](https://github.com/andrebrait))
+
+### Added
+
+- Added `Agent.setOnModelCallSystemPrompt`, called with the exact system prompt each model call is built from ([#14338](https://github.com/can1357/oh-my-pi/pull/14338) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Changed
+
+- `SessionInitEntry.systemPrompt` holds the system prompt blocks as sent; session files written earlier keep one joined string ([#14338](https://github.com/can1357/oh-my-pi/pull/14338) by [@will-bogusz](https://github.com/will-bogusz))
+- Image token estimates now use the catalog's `imageTokens()` formula with its OpenAI Responses wire rule; values are unchanged ([#14286](https://github.com/can1357/oh-my-pi/pull/14286) by [@will-bogusz](https://github.com/will-bogusz)).
+
+### Fixed
+
+- Fixed the context count and auto-compaction trigger pricing every snapcompact archive frame at Opus's high-res rate, which overcounted Codex and Gemini sessions and could re-trigger compaction right after compacting ([#14291](https://github.com/can1357/oh-my-pi/pull/14291) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed native (OpenAI) compaction being refused as over the context window in sessions with many screenshots. Images were counted as about 1,200 tokens when deciding to compact but 12,000 when checking whether the compaction request fits; both checks now estimate images from their actual dimensions, and a request is no longer refused when only the image estimate pushes it over the window ([#14260](https://github.com/can1357/oh-my-pi/pull/14260) by [@H4vC](https://github.com/H4vC)).
+- Fixed OpenAI and Codex Remote Compaction V2 dropping your recent messages instead of keeping them next to the compaction summary ([#14247](https://github.com/can1357/oh-my-pi/pull/14247) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed the failed V2 remote compaction warning claiming a V1 fallback on Codex, where V1 does not run ([#14245](https://github.com/can1357/oh-my-pi/pull/14245) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Anthropic native compaction being rejected with `Invalid signature in thinking block` (or silently dropping the summarized thinking) on models with preserved thinking ([#14251](https://github.com/can1357/oh-my-pi/pull/14251) by [@will-bogusz](https://github.com/will-bogusz))
+
 ## [18.6.1] - 2026-10-04
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -390,8 +390,8 @@ export declare class Agent {
     get state(): AgentState;
     /**
      * Tokenizer for the active model. The instance is replaced whenever the
-     * active model's encoding changes (see {@link setModel}), so callers must
-     * not cache it across model switches.
+     * active model's encoding or snapcompact frame pricing changes (see
+     * {@link setModel}), so callers must not cache it across model switches.
      */
     get tokenizer(): Tokenizer;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
@@ -422,10 +422,15 @@ export declare class Agent {
     /** Register an independently removable hook that runs immediately before each model call. */
     addBeforeModelCallHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
     /**
-     * Take back live-steered messages ahead of an abort (Esc restores them to the editor):
-     * the aborted run then neither records nor requeues them.
+     * Take back dequeued input the transcript has not recorded yet, ahead of an abort (Esc restores
+     * it to the editor): steering live steering took for the in-flight response, then each batch
+     * dequeued for the next model call, oldest first. The aborted run then neither records it (or
+     * the context prepared for it) nor requeues it.
      */
-    withdrawLiveSteering(): AgentMessage[];
+    withdrawUndeliveredQueuedMessages(): {
+        steering: AgentMessage[];
+        followUp: AgentMessage[];
+    };
     /** Steering live steering took for the streaming response; the transcript records it once
      *  that response (or its tool batch) ends, which is when the model switches to it. */
     peekLiveSteeredMessages(): AgentMessage[];
@@ -434,6 +439,8 @@ export declare class Agent {
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void) | undefined): void;
+    /** Called with the exact system prompt each model call is built from, after before-model-call hooks. */
+    setOnModelCallSystemPrompt(fn: ((systemPrompt: string[]) => void) | undefined): void;
     /**
      * Install or replace the host pre-model-call gate; pass `undefined` to
      * remove it. Gates are sampled when a run starts: installing the first

package/dist/types/compaction/anthropic.d.ts

@@ -1,11 +1,12 @@
 /**
  * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The request sends only the prefix to summarize, with the live conversation's
- * system prompt, tools and thinking settings. The returned signed block
- * replaces that prefix; the retained tail is replayed from session entries.
+ * The request sends only the prefix to summarize, as the live conversation
+ * sent it: same system prompt, tools, history bytes and thinking settings.
+ * The returned signed block replaces that prefix; the retained tail is
+ * replayed from session entries.
  */
-import type { AnthropicCompactionPayload, ApiKey, Effort, Message, Model, SimpleStreamOptions, Tool, Usage } from "@oh-my-pi/pi-ai";
+import type { AnthropicCompactionFiles, AnthropicCompactionPayload, ApiKey, Context, Effort, Model, SimpleStreamOptions, Usage } from "@oh-my-pi/pi-ai";
 import { type InstrumentedChatSpanOptions } from "../telemetry.js";
 import type { AgentMessage } from "../types.js";
 export declare const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
@@ -17,8 +18,12 @@ export interface AnthropicCompactionPreserveData {
     signature?: string;
     /** Legacy threshold block state; replay-only. */
     encryptedContent?: string;
-    /** Harness file metadata (`<files>` section) replayed after the native block. */
+    /** Harness file metadata (`<files>` section) replayed after the retained tail. */
     filesText?: string;
+    /** Earlier summaries' file metadata replayed inside the retained tail. */
+    retainedFiles?: AnthropicCompactionFiles[];
+    /** The retained tail replays unchanged (see `AnthropicCompactionPayload.exactTail`). */
+    exactTail?: true;
     /** Model that wrote the summary. */
     model?: string;
     /** Prompt tokens the compaction request processed, for display. */
@@ -51,10 +56,11 @@ export declare function findAnthropicCompactionCut(messages: readonly (AgentMess
 /** Instructions replace the API default; the request contains only summarized messages. */
 export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined): string;
 export interface AnthropicNativeCompactionRequest {
-    systemPrompt: string[];
-    messages: Message[];
-    tools?: Tool[];
+    /** The summarized prefix as the live turn would send it. */
+    context: Context;
     instructions: string;
+    /** Replayed file metadata due before this time ends the request (see `AnthropicCompactionRequest.filesDueBefore`). */
+    filesDueBefore?: number;
     maxTokens: number;
     reasoning?: Effort;
 }

package/dist/types/compaction/compaction-v2-streaming.d.ts

@@ -26,6 +26,8 @@ export interface CompactionV2Usage {
 export interface CompactionV2Request {
     body: OpenAICodexCompactionBody;
     input: unknown[];
+    /** Serialized user-written turns to keep next to the compaction item; defaults to `input`. */
+    retainedUserItems: unknown[];
     retainedMessageBudget: number;
     sessionId?: string;
     promptCacheKey?: string;
@@ -56,12 +58,14 @@ export declare function buildCompactionV2Request(model: Model, input: unknown[],
     sessionId?: string;
     promptCacheKey?: string;
     retainedMessageBudget?: number;
+    retainedUserItems?: unknown[];
 }): CompactionV2Request;
 /** Wrap a body built by the normal Codex serializer for V2 compaction transport. */
 export declare function buildCompactionV2RequestFromBody(model: Model, body: OpenAICodexCompactionBody, options?: {
     sessionId?: string;
     promptCacheKey?: string;
     retainedMessageBudget?: number;
+    retainedUserItems?: unknown[];
 }): CompactionV2Request;
 /** Request V2 compaction over the normal OpenAI Responses streaming endpoint. */
 export declare function requestCompactionV2Streaming(model: Model, apiKey: string, request: CompactionV2Request, signal?: AbortSignal, options?: {
@@ -72,7 +76,7 @@ export declare function requestCompactionV2Streaming(model: Model, apiKey: strin
     codexCompaction?: CodexCompactionContext;
     preferWebsockets?: boolean;
 }): Promise<CompactionV2Response>;
-/** Build Codex-style V2 replacement history from prompt input plus compaction output. */
+/** Build Codex-style V2 replacement history from retention candidates plus compaction output. */
 export declare function buildCompactionV2ReplacementHistory(input: unknown[], compactionItem: Record<string, unknown>, retainedMessageBudget?: number): {
     replacementHistory: Array<Record<string, unknown>>;
     retainedImageCount: number;

package/dist/types/compaction/compaction.d.ts

@@ -177,6 +177,20 @@ export interface SummaryOptions {
     initiatorOverride?: MessageAttribution;
     metadata?: Record<string, unknown>;
     convertToLlm?: ConvertToLlm;
+    /**
+     * The provider context a live turn sends for `summarized` + `retained`, cut to
+     * `summarized`. Anthropic on-demand compaction sends it so retained signed
+     * thinking keeps its prefix; without it the request uses `remoteSystemPrompt`,
+     * `tools` and `convertToLlm`.
+     */
+    buildProviderContext?: (summarized: AgentMessage[], retained: AgentMessage[], signal?: AbortSignal) => Promise<Context>;
+    /**
+     * Whether a message is a turn the user wrote. Remote Compaction V2 keeps these
+     * next to the compaction item. Defaults to `role === "user"`; hosts whose
+     * user-initiated turns also arrive as custom messages (e.g. skill invocations)
+     * widen it.
+     */
+    isUserAuthored?: (message: AgentMessage) => boolean;
     /**
      * Optional telemetry handle. When provided, every LLM call emitted during
      * compaction is wrapped in an OTEL chat span tagged with

package/dist/types/compaction/entries.d.ts

@@ -88,8 +88,8 @@ export interface TtsrInjectionEntry extends SessionEntryBase {
 }
 export interface SessionInitEntry extends SessionEntryBase {
     type: "session_init";
-    /** Full system prompt sent to the model */
-    systemPrompt: string;
+    /** System prompt blocks exactly as sent to the model; files written before blocks were kept store one joined string. */
+    systemPrompt: string[] | string;
     /** Initial task/user message */
     task: string;
     /** Tools available to the agent */

package/dist/types/compaction/openai.d.ts

@@ -28,6 +28,12 @@ export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompac
  */
 export declare const REMOTE_COMPACTION_TIMEOUT_MS = 300000;
 export declare const CONTEXT_WINDOW_TRUNCATED_OUTPUT_MESSAGE: string;
+/**
+ * Tokens of stored Responses replacement history. Retained `input_image` parts
+ * count at their image estimate rather than as base64 text; everything else,
+ * opaque compaction state included, counts as serialized.
+ */
+export declare function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number;
 export interface TrimRemoteCompactionInputResult {
     input: Array<Record<string, unknown>>;
     rewrittenOutputs: number;

package/dist/types/image-tokens.d.ts

@@ -1,4 +1,5 @@
 import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { type ImageSize } from "@oh-my-pi/pi-catalog/compat/image-tokenization";
 /**
  * Dimension-based image token estimates shared by the local context counter
  * ({@link Tokenizer.countMessage}) and the native remote-compaction fit probe.
@@ -7,16 +8,14 @@ import type { ImageContent } from "@oh-my-pi/pi-ai";
  * stayed under the local compaction trigger yet was refused as over-window by
  * the remote probe.
  *
- * Follows OpenAI's patch-based rule (32px patches, a per-detail pixel limit
- * and patch budget, x1.2 multiplier), which is also a close upper estimate for
- * other providers once omp has downscaled the image (≤1568px by default).
+ * Follows the catalog's image rule for the OpenAI Responses wire (GPT-5.5's
+ * 32px patches, a per-detail pixel limit and patch budget, x1.2 multiplier),
+ * which is also a close upper estimate for other providers once omp has
+ * downscaled the image (≤1568px by default).
  */
 /** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
 export type ImageDetail = ImageContent["detail"];
-export interface ImageSize {
-    width: number;
-    height: number;
-}
+export type { ImageSize };
 /**
  * Estimated input tokens for one image. Unknown dimensions (undecodable data,
  * remote URLs, provider file ids) charge the detail level's full patch budget.

package/dist/types/telemetry.d.ts

@@ -520,8 +520,8 @@ export interface InstrumentedChatSpanOptions {
     /**
      * Tag stamped onto `omp.gen_ai.oneshot.kind`. Values used by the agent:
      * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
-     * `handoff`, `branch_summary`, `image_question`. Free-form to allow callers
-     * outside this package to add new kinds without bumping the helper.
+     * `handoff`, `branch_summary`, `image_question`, `skill_description`. Free-form
+     * to allow callers outside this package to add new kinds without bumping the helper.
      */
     readonly oneshotKind?: string;
     /** Extra span attributes applied verbatim. */

package/dist/types/tokenizer.d.ts

@@ -1,5 +1,6 @@
 import type { Model } from "@oh-my-pi/pi-ai";
 import * as natives from "@oh-my-pi/pi-natives";
+import * as snapcompact from "@oh-my-pi/snapcompact";
 import type { AgentMessage } from "./types.js";
 /** Maps the catalog-resolved tokenizer family to its native implementation. */
 export declare function tokenizerEncodingForModel(model: Pick<Model, "tokenizer"> | null | undefined): natives.Encoding | null;
@@ -42,14 +43,15 @@ export interface TokenBudgetCheck {
  * Model-aware local token counter. Immutable: the catalog-resolved encoding
  * is fixed at construction, so a cached count can never straddle two
  * encodings. An `Agent` owns one for its active model (swapping the instance
- * when the model's encoding changes); one-shot flows construct their own for
- * the model that will be billed. Known tokenizer families use exact native
- * counts; unknown models keep the fast byte estimate (or o200k when
- * `PI_TOKENIZER_ACCURATE=1`).
+ * when the model's encoding or snapcompact frame pricing changes); one-shot
+ * flows construct their own for the model that will be billed. Known
+ * tokenizer families use exact native counts; unknown models keep the fast
+ * byte estimate (or o200k when `PI_TOKENIZER_ACCURATE=1`).
  */
 export declare class Tokenizer {
     #private;
-    constructor(model?: Pick<Model, "tokenizer"> | null);
+    readonly frameBillingKey: string;
+    constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null);
     get encoding(): natives.Encoding | null;
     countTokens(text: string | string[], mode?: TokenCountMode): number;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.6.1",
+	"version": "18.7.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -38,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.6.1",
-		"@oh-my-pi/pi-catalog": "18.6.1",
-		"@oh-my-pi/pi-natives": "18.6.1",
-		"@oh-my-pi/pi-utils": "18.6.1",
-		"@oh-my-pi/pi-wire": "18.6.1",
-		"@oh-my-pi/snapcompact": "18.6.1",
+		"@oh-my-pi/pi-ai": "18.7.0",
+		"@oh-my-pi/pi-catalog": "18.7.0",
+		"@oh-my-pi/pi-natives": "18.7.0",
+		"@oh-my-pi/pi-utils": "18.7.0",
+		"@oh-my-pi/pi-wire": "18.7.0",
+		"@oh-my-pi/snapcompact": "18.7.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.6.1",
+		"@oh-my-pi/omptype": "18.7.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent.ts

@@ -26,6 +26,7 @@ import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
 import { getBundledModel } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
+import * as snapcompact from "@oh-my-pi/snapcompact";
 import {
 	abortReasonText,
 	agentLoop,
@@ -386,6 +387,13 @@ interface CursorToolResultEntry {
 
 type QueuedMessageQueue = "steering" | "followUp";
 
+interface LiveSteeredEntry {
+	message: AgentMessage;
+	controller: AbortController | undefined;
+	/** Context preparation committed for the batch, carried by its last adopted entry. Never requeued. */
+	additional?: readonly AgentMessage[];
+}
+
 interface QueuedMessageClaim {
 	messages: AgentMessage[];
 	controller: AbortController;
@@ -420,16 +428,20 @@ export class Agent {
 	 * transcript has not recorded yet, whether or not the provider accepted it. Kept apart from
 	 * {@link #queuedMessageDeliveries}: the loop drops it on abort instead of recording it, so queue
 	 * replacement must not drop it too; the run's end requeues whatever it did not record, and
-	 * {@link withdrawLiveSteering} takes it back ahead of an abort.
+	 * {@link withdrawUndeliveredQueuedMessages} takes it back ahead of an abort.
 	 */
-	#liveSteered: { message: AgentMessage; controller: AbortController | undefined }[] = [];
-	/** Dequeued originals remain recoverable until their transcript events arrive. */
+	#liveSteered: LiveSteeredEntry[] = [];
+	/** Dequeued originals remain recoverable until their transcript events arrive. `additional` is
+	 *  the context preparation appended after them, which the transcript records with them. */
 	#queuedMessageDeliveries = new Set<{
 		queue: QueuedMessageQueue;
 		controller: AbortController | undefined;
 		messages: AgentMessage[];
 		next: number;
+		additional: readonly AgentMessage[];
 	}>();
+	/** Messages {@link withdrawUndeliveredQueuedMessages} took back, keyed to the run that must not record them. */
+	#withdrawnMessages = new WeakMap<AgentMessage, AbortController>();
 	#steeringWaiters = new Set<() => void>();
 	#queuedMessageGrouping?: (previous: AgentMessage, next: AgentMessage) => boolean;
 
@@ -484,6 +496,7 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#onTurnEnd?: (messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void;
+	#onModelCallSystemPrompt?: (systemPrompt: string[]) => void;
 	#beforeModelCall?: AgentBeforeModelCall;
 	#additionalBeforeModelCalls = new Set<AgentBeforeModelCall>();
 	#asideMessageProvider?: () => AsideMessage[] | Promise<AsideMessage[]>;
@@ -831,19 +844,22 @@ export class Agent {
 
 	/**
 	 * Tokenizer for the active model. The instance is replaced whenever the
-	 * active model's encoding changes (see {@link setModel}), so callers must
-	 * not cache it across model switches.
+	 * active model's encoding or snapcompact frame pricing changes (see
+	 * {@link setModel}), so callers must not cache it across model switches.
 	 */
 	get tokenizer(): Tokenizer {
 		return this.#tokenizer;
 	}
 
 	/**
-	 * Swap the tokenizer only when the encoding actually changes, so the warm
-	 * per-message memo survives same-encoding model switches.
+	 * Swap the tokenizer only when the encoding or frame pricing actually
+	 * changes, so the warm per-message memo survives same-pricing model switches.
 	 */
 	#syncTokenizer(model: Model | null | undefined): void {
-		if (tokenizerEncodingForModel(model) !== this.#tokenizer.encoding) {
+		if (
+			tokenizerEncodingForModel(model) !== this.#tokenizer.encoding ||
+			snapcompact.frameBillingKey(snapcompact.frameBilling(model ?? undefined)) !== this.#tokenizer.frameBillingKey
+		) {
 			this.#tokenizer = new Tokenizer(model);
 		}
 	}
@@ -967,7 +983,7 @@ export class Agent {
 		if (messages.length === 0) return messages;
 		const runController = this.#abortController;
 		if (!prepare) {
-			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0 });
+			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0, additional: [] });
 			return messages;
 		}
 
@@ -986,7 +1002,13 @@ export class Agent {
 				throw new DOMException("Queued message preparation cancelled", "AbortError");
 			}
 			delete this.#queuedMessageClaims[queue];
-			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0 });
+			this.#queuedMessageDeliveries.add({
+				queue,
+				controller: runController,
+				messages,
+				next: 0,
+				additional: additional ?? [],
+			});
 			return additional?.length ? [...messages, ...additional] : messages;
 		} catch (error) {
 			if (signal.aborted) throw error;
@@ -1048,10 +1070,15 @@ export class Agent {
 			const pending = delivery.messages.slice(delivery.next);
 			const kept = pending.filter(message => !taken.includes(message));
 			if (kept.length === pending.length) continue;
+			let last: LiveSteeredEntry | undefined;
 			for (const message of pending) {
-				if (taken.includes(message)) this.#liveSteered.push({ message, controller: delivery.controller });
+				if (!taken.includes(message)) continue;
+				last = { message, controller: delivery.controller };
+				this.#liveSteered.push(last);
 			}
 			if (kept.length === 0) {
+				// The delivery record goes away; keep its context withdrawable with the adopted batch.
+				if (last && delivery.additional.length > 0) last.additional = delivery.additional;
 				this.#queuedMessageDeliveries.delete(delivery);
 			} else {
 				delivery.messages = kept;
@@ -1061,13 +1088,29 @@ export class Agent {
 	}
 
 	/**
-	 * Take back live-steered messages ahead of an abort (Esc restores them to the editor):
-	 * the aborted run then neither records nor requeues them.
+	 * Take back dequeued input the transcript has not recorded yet, ahead of an abort (Esc restores
+	 * it to the editor): steering live steering took for the in-flight response, then each batch
+	 * dequeued for the next model call, oldest first. The aborted run then neither records it (or
+	 * the context prepared for it) nor requeues it.
 	 */
-	withdrawLiveSteering(): AgentMessage[] {
-		const messages = this.peekLiveSteeredMessages();
+	withdrawUndeliveredQueuedMessages(): { steering: AgentMessage[]; followUp: AgentMessage[] } {
+		const withdrawn: Record<QueuedMessageQueue, AgentMessage[]> = { steering: [], followUp: [] };
+		const suppress = (message: AgentMessage, controller: AbortController | undefined) => {
+			if (controller) this.#withdrawnMessages.set(message, controller);
+		};
+		for (const { message, controller, additional } of this.#liveSteered) {
+			withdrawn.steering.push(message);
+			suppress(message, controller);
+			for (const context of additional ?? []) suppress(context, controller);
+		}
 		this.#liveSteered = [];
-		return messages;
+		for (const delivery of this.#queuedMessageDeliveries) {
+			const pending = delivery.messages.slice(delivery.next);
+			withdrawn[delivery.queue].push(...pending);
+			for (const message of [...pending, ...delivery.additional]) suppress(message, delivery.controller);
+		}
+		this.#queuedMessageDeliveries.clear();
+		return withdrawn;
 	}
 
 	/** Steering live steering took for the streaming response; the transcript records it once
@@ -1101,6 +1144,11 @@ export class Agent {
 		this.#onTurnEnd = fn;
 	}
 
+	/** Called with the exact system prompt each model call is built from, after before-model-call hooks. */
+	setOnModelCallSystemPrompt(fn: ((systemPrompt: string[]) => void) | undefined): void {
+		this.#onModelCallSystemPrompt = fn;
+	}
+
 	/**
 	 * Install or replace the host pre-model-call gate; pass `undefined` to
 	 * remove it. Gates are sampled when a run starts: installing the first
@@ -1800,6 +1848,7 @@ export class Agent {
 					await Bun.sleep(0);
 				}
 				context.systemPrompt = this.#state.systemPrompt;
+				this.#onModelCallSystemPrompt?.(context.systemPrompt);
 				context.tools = this.#toolsForModel(this.#state.model ?? model);
 			},
 			beforeModelCall:
@@ -1879,8 +1928,19 @@ export class Agent {
 				? agentLoop(messages, context, config, loopSignal, this.streamFn)
 				: agentLoopContinue(context, config, loopSignal, this.streamFn);
 
-			for await (const event of stream) {
+			for await (let event of stream) {
 				if (this.#abortController !== loopAbortController) return;
+				// Withdrawn input the loop already holds for this run never reaches the transcript.
+				if (
+					(event.type === "message_start" || event.type === "message_end") &&
+					this.#withdrawnMessages.get(event.message) === loopAbortController
+				) {
+					continue;
+				}
+				if (event.type === "agent_end") {
+					const messages = event.messages.filter(m => this.#withdrawnMessages.get(m) !== loopAbortController);
+					if (messages.length < event.messages.length) event = { ...event, messages };
+				}
 				if (event.type === "turn_start") turnOpen = true;
 				if (event.type === "turn_end") turnOpen = false;
 				// Update internal state based on events
@@ -2058,8 +2118,19 @@ export class Agent {
 				turnOpen = false;
 				this.#emit({ type: "agent_end", messages: agentEndMessages });
 			} else {
+				// Context hooks can reject on abort before provider streaming starts.
+				// Publish the boundary just like a streaming abort so subscribers can
+				// persist it and recover the interrupted turn after a reload.
+				if (!turnOpen) this.#emit({ type: "turn_start" });
+				if (!hadAssistantStart) {
+					this.#state.streamMessage = errorMsg;
+					this.#emit({ type: "message_start", message: errorMsg });
+				}
+				this.#state.streamMessage = null;
 				this.appendMessage(errorMsg);
 				this.#state.error = errorMessage;
+				this.#emit({ type: "message_end", message: errorMsg });
+				this.#emit({ type: "turn_end", message: errorMsg, toolResults: [] });
 				this.#emit({ type: "agent_end", messages: [errorMsg] });
 			}
 		} finally {

package/src/compaction/anthropic.ts

@@ -1,22 +1,24 @@
 /**
  * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The request sends only the prefix to summarize, with the live conversation's
- * system prompt, tools and thinking settings. The returned signed block
- * replaces that prefix; the retained tail is replayed from session entries.
+ * The request sends only the prefix to summarize, as the live conversation
+ * sent it: same system prompt, tools, history bytes and thinking settings.
+ * The returned signed block replaces that prefix; the retained tail is
+ * replayed from session entries.
  */
 
 import type {
+	AnthropicCompactionFiles,
 	AnthropicCompactionPayload,
 	ApiKey,
+	Context,
 	Effort,
-	Message,
 	Model,
 	SimpleStreamOptions,
-	Tool,
 	Usage,
 } from "@oh-my-pi/pi-ai";
 import * as AIError from "@oh-my-pi/pi-ai/error";
+import { resolveAnthropicCompactionEffort } from "@oh-my-pi/pi-ai/providers/anthropic";
 import { supportsAnthropicCompaction } from "@oh-my-pi/pi-ai/providers/anthropic-compaction";
 import { isRecord, prompt } from "@oh-my-pi/pi-utils";
 import { type InstrumentedChatSpanOptions, instrumentedCompleteSimple } from "../telemetry";
@@ -33,8 +35,12 @@ export interface AnthropicCompactionPreserveData {
 	signature?: string;
 	/** Legacy threshold block state; replay-only. */
 	encryptedContent?: string;
-	/** Harness file metadata (`<files>` section) replayed after the native block. */
+	/** Harness file metadata (`<files>` section) replayed after the retained tail. */
 	filesText?: string;
+	/** Earlier summaries' file metadata replayed inside the retained tail. */
+	retainedFiles?: AnthropicCompactionFiles[];
+	/** The retained tail replays unchanged (see `AnthropicCompactionPayload.exactTail`). */
+	exactTail?: true;
 	/** Model that wrote the summary. */
 	model?: string;
 	/** Prompt tokens the compaction request processed, for display. */
@@ -76,6 +82,15 @@ export function getPreservedAnthropicCompactionData(
 		...(typeof candidate.filesText === "string" && candidate.filesText.length > 0
 			? { filesText: candidate.filesText }
 			: {}),
+		...(Array.isArray(candidate.retainedFiles) && candidate.retainedFiles.length > 0
+			? {
+					retainedFiles: candidate.retainedFiles.filter(
+						(files): files is AnthropicCompactionFiles =>
+							isRecord(files) && typeof files.text === "string" && typeof files.after === "number",
+					),
+				}
+			: {}),
+		...(candidate.exactTail === true ? { exactTail: true as const } : {}),
 		...(typeof candidate.model === "string" ? { model: candidate.model } : {}),
 		...(typeof candidate.usedTokens === "number" ? { usedTokens: candidate.usedTokens } : {}),
 	};
@@ -109,6 +124,8 @@ export function getAnthropicCompactionPayload(
 		...(preserved.signature ? { signature: preserved.signature } : {}),
 		...(preserved.encryptedContent ? { encryptedContent: preserved.encryptedContent } : {}),
 		...(preserved.filesText ? { filesText: preserved.filesText } : {}),
+		...(preserved.retainedFiles?.length ? { retainedFiles: preserved.retainedFiles } : {}),
+		...(preserved.exactTail ? { exactTail: true as const } : {}),
 	};
 }
 
@@ -167,10 +184,11 @@ export function buildAnthropicCompactionInstructions(
 }
 
 export interface AnthropicNativeCompactionRequest {
-	systemPrompt: string[];
-	messages: Message[];
-	tools?: Tool[];
+	/** The summarized prefix as the live turn would send it. */
+	context: Context;
 	instructions: string;
+	/** Replayed file metadata due before this time ends the request (see `AnthropicCompactionRequest.filesDueBefore`). */
+	filesDueBefore?: number;
 	maxTokens: number;
 	reasoning?: Effort;
 }
@@ -214,12 +232,12 @@ export async function requestAnthropicNativeCompaction(
 ): Promise<AnthropicNativeCompactionResponse> {
 	const response = await instrumentedCompleteSimple(
 		model,
-		{ systemPrompt: request.systemPrompt, messages: request.messages, tools: request.tools },
+		request.context,
 		{
 			apiKey,
 			signal,
 			maxTokens: request.maxTokens,
-			reasoning: request.reasoning,
+			reasoning: resolveAnthropicCompactionEffort(model, request.context.messages, request.reasoning),
 			initiatorOverride: options.initiatorOverride,
 			metadata: options.metadata,
 			fetch: options.fetch,
@@ -227,7 +245,7 @@ export async function requestAnthropicNativeCompaction(
 			promptCacheKey: options.promptCacheKey,
 			providerSessionState: options.providerSessionState,
 			maxInFlightRequests: options.maxInFlightRequests,
-			anthropicCompaction: { instructions: request.instructions },
+			anthropicCompaction: { instructions: request.instructions, filesDueBefore: request.filesDueBefore },
 		},
 		{
 			telemetry: options.telemetry,

package/src/compaction/compaction-v2-streaming.ts

@@ -77,6 +77,8 @@ export interface CompactionV2Usage {
 export interface CompactionV2Request {
 	body: OpenAICodexCompactionBody;
 	input: unknown[];
+	/** Serialized user-written turns to keep next to the compaction item; defaults to `input`. */
+	retainedUserItems: unknown[];
 	retainedMessageBudget: number;
 	sessionId?: string;
 	promptCacheKey?: string;
@@ -190,6 +192,7 @@ export function buildCompactionV2Request(
 		sessionId?: string;
 		promptCacheKey?: string;
 		retainedMessageBudget?: number;
+		retainedUserItems?: unknown[];
 	},
 ): CompactionV2Request {
 	const cacheOptions = { sessionId: options?.sessionId, promptCacheKey: options?.promptCacheKey };
@@ -223,12 +226,14 @@ export function buildCompactionV2RequestFromBody(
 		sessionId?: string;
 		promptCacheKey?: string;
 		retainedMessageBudget?: number;
+		retainedUserItems?: unknown[];
 	},
 ): CompactionV2Request {
 	const input = Array.isArray(body.input) ? body.input : [];
 	return {
 		body: { ...body, model: resolveCompactionV2Model(model), input },
 		input,
+		retainedUserItems: options?.retainedUserItems ?? input,
 		retainedMessageBudget: resolveCompactionV2RetainedMessageBudget(options?.retainedMessageBudget),
 		sessionId: options?.sessionId,
 		promptCacheKey: options?.promptCacheKey,
@@ -536,7 +541,7 @@ function finishCompactionV2Collection(
 
 	const compactionItem = state.compactionItems[0];
 	const { replacementHistory, retainedImageCount } = buildCompactionV2ReplacementHistory(
-		request.input,
+		request.retainedUserItems,
 		compactionItem,
 		request.retainedMessageBudget,
 	);
@@ -665,15 +670,14 @@ function isRetryableCompactionError(error: Error): boolean {
 // Replacement History
 // ============================================================================
 
-/** Build Codex-style V2 replacement history from prompt input plus compaction output. */
+/** Build Codex-style V2 replacement history from retention candidates plus compaction output. */
 export function buildCompactionV2ReplacementHistory(
 	input: unknown[],
 	compactionItem: Record<string, unknown>,
 	retainedMessageBudget = V2_RETAINED_MESSAGE_TOKEN_BUDGET,
 ): { replacementHistory: Array<Record<string, unknown>>; retainedImageCount: number } {
 	const retained = input.filter(
-		(item): item is Record<string, unknown> =>
-			isRecord(item) && isRetainedForCompactionV2(item) && shouldKeepCompactionV2HistoryItem(item),
+		(item): item is Record<string, unknown> => isRecord(item) && isRetainedUserMessageForCompactionV2(item),
 	);
 	const replacementHistory = truncateRetainedMessagesForCompactionV2(
 		retained,
@@ -684,17 +688,11 @@ export function buildCompactionV2ReplacementHistory(
 	return { replacementHistory, retainedImageCount };
 }
 
-function isRetainedForCompactionV2(item: Record<string, unknown>): boolean {
-	if (item.type !== "message") return false;
-	const role = stringField(item, "role");
-	return role === "user" || role === "developer" || role === "system";
-}
-
-function shouldKeepCompactionV2HistoryItem(item: Record<string, unknown>): boolean {
-	if (item.type !== "message") return item.type === "compaction";
-	const role = stringField(item, "role");
-	if (role !== "user") return false;
-	return !isContextualUserMessage(item);
+function isRetainedUserMessageForCompactionV2(item: Record<string, unknown>): boolean {
+	// Responses input messages may omit `type`: omp serializes turns as
+	// `{ role, content }`, which the API reads as `type: "message"`.
+	const isMessage = item.type === "message" || (item.type === undefined && typeof item.role === "string");
+	return isMessage && item.role === "user" && !isContextualUserMessage(item);
 }
 
 function isContextualUserMessage(item: Record<string, unknown>): boolean {

package/src/compaction/compaction.ts

@@ -6,6 +6,7 @@
  */
 
 import {
+	type AnthropicCompactionFiles,
 	type Api,
 	type ApiKey,
 	type AssistantMessage,
@@ -676,6 +677,24 @@ export interface SummaryOptions {
 	initiatorOverride?: MessageAttribution;
 	metadata?: Record<string, unknown>;
 	convertToLlm?: ConvertToLlm;
+	/**
+	 * The provider context a live turn sends for `summarized` + `retained`, cut to
+	 * `summarized`. Anthropic on-demand compaction sends it so retained signed
+	 * thinking keeps its prefix; without it the request uses `remoteSystemPrompt`,
+	 * `tools` and `convertToLlm`.
+	 */
+	buildProviderContext?: (
+		summarized: AgentMessage[],
+		retained: AgentMessage[],
+		signal?: AbortSignal,
+	) => Promise<Context>;
+	/**
+	 * Whether a message is a turn the user wrote. Remote Compaction V2 keeps these
+	 * next to the compaction item. Defaults to `role === "user"`; hosts whose
+	 * user-initiated turns also arrive as custom messages (e.g. skill invocations)
+	 * widen it.
+	 */
+	isUserAuthored?: (message: AgentMessage) => boolean;
 	/**
 	 * Optional telemetry handle. When provided, every LLM call emitted during
 	 * compaction is wrapped in an OTEL chat span tagged with
@@ -1612,6 +1631,8 @@ export async function compact(
 		initiatorOverride: options?.initiatorOverride,
 		metadata: options?.metadata,
 		convertToLlm: options?.convertToLlm,
+		buildProviderContext: options?.buildProviderContext,
+		isUserAuthored: options?.isUserAuthored,
 		telemetry: options?.telemetry,
 		// Honor /model thinking selection on every fan-out summarizer.
 		// Without this propagation, generateSummary / generateTurnPrefixSummary
@@ -1675,7 +1696,17 @@ export async function compact(
 			previousRemoteCompaction?.provider === model.provider
 				? previousRemoteCompaction.replacementHistory
 				: undefined;
-		const messages = (summaryOptions.convertToLlm ?? defaultConvertToLlm)(remoteMessages);
+		const convertToLlm = summaryOptions.convertToLlm ?? defaultConvertToLlm;
+		const messages = convertToLlm(remoteMessages);
+		// Replacement history keeps what the user wrote. Summaries, archive
+		// migrations, and custom/hook messages can serialize as user-role items
+		// too, so pick the user's own messages before serialization erases that,
+		// then serialize each one exactly as the request does.
+		const isUserAuthored = summaryOptions.isUserAuthored ?? ((message: AgentMessage) => message.role === "user");
+		const userMessages = convertToLlm(
+			[...messagesToSummarize, ...turnPrefixMessages, ...recentMessages].filter(isUserAuthored),
+		);
+		const retainedUserItems: unknown[] = [...(previousReplacementHistory ?? [])];
 		const remoteSystemPrompt = summaryOptions.remoteSystemPrompt ?? [SUMMARIZATION_SYSTEM_PROMPT];
 		let codexBody: OpenAICodexCompactionBody | undefined;
 		let remoteHistory: Array<Record<string, unknown>>;
@@ -1715,8 +1746,19 @@ export async function compact(
 			}
 			remoteHistory = stripOpenAIResponsesOutputOnlyStatusesForReplay(nativeInput);
 			codexBody.input = remoteHistory;
+			for (const message of userMessages) {
+				const userBody = await buildTransformedCodexRequestBody(
+					model,
+					{ messages: [message] },
+					{ responsesLite: model.useResponsesLite },
+				);
+				retainedUserItems.push(...(userBody.input ?? []));
+			}
 		} else {
 			remoteHistory = buildOpenAiResponsesCompactionInput(messages, model, previousReplacementHistory);
+			for (const message of userMessages) {
+				retainedUserItems.push(...buildOpenAiResponsesCompactionInput([message], model, undefined));
+			}
 		}
 		if (remoteHistory.length > 0) {
 			try {
@@ -1754,6 +1796,7 @@ export async function compact(
 					sessionId: summaryOptions.sessionId,
 					promptCacheKey: summaryOptions.promptCacheKey,
 					retainedMessageBudget: settings.v2RetainedMessageBudget,
+					retainedUserItems,
 				};
 				const request = codexBody
 					? buildCompactionV2RequestFromBody(model, { ...codexBody, input: trimmed.input }, requestOptions)
@@ -1781,11 +1824,17 @@ export async function compact(
 				// summarization" and keep compaction running on an aborted signal.
 				if (signal?.aborted) throw err;
 				nativeCompactionError = selectNativeCompactionError(nativeCompactionError, err);
-				logger.warn("OpenAI V2 remote compaction failed, falling back to V1 remote compaction", {
-					error: err instanceof Error ? err.message : String(err),
-					model: model.id,
-					provider: model.provider,
-				});
+				// Claim the V1 fallback only when the V1 block below will run.
+				logger.warn(
+					shouldUseOpenAiRemoteCompaction(model)
+						? "OpenAI V2 remote compaction failed, falling back to V1 remote compaction"
+						: "OpenAI V2 remote compaction failed",
+					{
+						error: err instanceof Error ? err.message : String(err),
+						model: model.id,
+						provider: model.provider,
+					},
+				);
 			}
 		}
 	}
@@ -1848,32 +1897,40 @@ export async function compact(
 	let nativeSignature: string | undefined;
 	let nativeFirstKeptEntryId = firstKeptEntryId;
 	let nativeUsedTokens: number | undefined;
+	let nativeRetainedFiles: AnthropicCompactionFiles[] | undefined;
 	if (!usedRemoteCompaction && settings.remoteEnabled !== false && shouldUseAnthropicNativeCompaction(model)) {
 		const previousNative = getPreservedAnthropicCompactionData(previousPreserveData);
 		// Lead with the previous summary as the live context renders it:
 		// natively when this provider wrote it, as text otherwise.
 		// A prior snapcompact archive is already merged into that summary
-		// text. Predate the rewrite marker before all replayed messages so
+		// text. Like the live context, the summary keeps its commit time and
+		// predates its rewrite marker before all replayed messages, so
 		// retained thinking stays bound to the original prefix.
 		const firstReplayed = messagesToSummarize[0] ?? turnPrefixMessages[0] ?? recentMessages[0];
-		const previousSummaryAt =
-			firstReplayed !== undefined ? new Date(firstReplayed.timestamp - 1).toISOString() : new Date().toISOString();
 		const previousSummaryMessage = previousSummaryForCompaction
-			? createCompactionSummaryMessage(previousSummaryForCompaction, tokensBefore, previousSummaryAt, {
-					providerPayload:
-						previousNative?.provider === model.provider
-							? {
-									type: "anthropicCompaction",
-									provider: previousNative.provider,
-									content: previousNative.content,
-									...(previousNative.signature ? { signature: previousNative.signature } : {}),
-									...(previousNative.encryptedContent
-										? { encryptedContent: previousNative.encryptedContent }
-										: {}),
-									...(previousNative.filesText ? { filesText: previousNative.filesText } : {}),
-								}
-							: undefined,
-				})
+			? createCompactionSummaryMessage(
+					previousSummaryForCompaction,
+					tokensBefore,
+					preparation.previousSummaryTimestamp ?? new Date().toISOString(),
+					{
+						historyRewriteAt: firstReplayed !== undefined ? firstReplayed.timestamp - 1 : undefined,
+						providerPayload:
+							previousNative?.provider === model.provider
+								? {
+										type: "anthropicCompaction",
+										provider: previousNative.provider,
+										content: previousNative.content,
+										...(previousNative.signature ? { signature: previousNative.signature } : {}),
+										...(previousNative.encryptedContent
+											? { encryptedContent: previousNative.encryptedContent }
+											: {}),
+										...(previousNative.filesText ? { filesText: previousNative.filesText } : {}),
+										...(previousNative.retainedFiles ? { retainedFiles: previousNative.retainedFiles } : {}),
+										...(previousNative.exactTail ? { exactTail: true as const } : {}),
+									}
+								: undefined,
+					},
+				)
 			: undefined;
 		const allMessages = [...messagesToSummarize, ...turnPrefixMessages, ...recentMessages];
 		const originalCut = messagesToSummarize.length + turnPrefixMessages.length;
@@ -1891,20 +1948,57 @@ export async function compact(
 					? firstKeptEntryId
 					: (recentEntryIds?.[safeCut - originalCut] ?? "");
 		for (let i = originalCut; i < safeCut; i++) extractFileOpsFromMessage(allMessages[i], fileOps);
-		const messages = (summaryOptions.convertToLlm ?? defaultConvertToLlm)([
+		const summarizedMessages = [
 			...(previousSummaryMessage ? [previousSummaryMessage] : []),
 			...allMessages.slice(0, safeCut),
-		]);
+		];
+		// Earlier file metadata replays before the first message created after
+		// its summary. Metadata due inside the new retained tail stays out of the
+		// request, and the new summary keeps replaying it. So does metadata due
+		// right at the cut when the first kept message is a user-side turn: live
+		// requests sent it merged into that turn, and ending the request with it
+		// would merge the summarized range into the kept turn instead, which
+		// invalidates the kept thinking.
+		const firstRetained = allMessages[safeCut];
+		const filesDueBefore =
+			firstRetained === undefined
+				? undefined
+				: firstRetained.role === "assistant"
+					? firstRetained.timestamp
+					: (allMessages.slice(0, safeCut).findLast(message => message.role !== "toolResult")?.timestamp ??
+						Number.NEGATIVE_INFINITY);
+		const previousPayload = previousSummaryMessage?.providerPayload;
+		if (
+			filesDueBefore !== undefined &&
+			previousSummaryMessage !== undefined &&
+			previousPayload?.type === "anthropicCompaction" &&
+			previousPayload.exactTail
+		) {
+			const carried = [
+				...(previousPayload.retainedFiles ?? []),
+				...(previousPayload.filesText
+					? [{ text: previousPayload.filesText, after: previousSummaryMessage.timestamp }]
+					: []),
+			].filter(files => files.after >= filesDueBefore);
+			if (carried.length > 0) nativeRetainedFiles = carried;
+		}
 		try {
+			// The live turn's own system prompt, wire tools and transformed
+			// history when the host can build them: kept thinking remains valid
+			// only when the summarized prefix matches what was sent byte for byte.
+			const context = summaryOptions.buildProviderContext
+				? await summaryOptions.buildProviderContext(summarizedMessages, allMessages.slice(safeCut), signal)
+				: {
+						systemPrompt: summaryOptions.remoteSystemPrompt ?? [],
+						messages: (summaryOptions.convertToLlm ?? defaultConvertToLlm)(summarizedMessages),
+						tools: summaryOptions.tools,
+					};
 			const remote = await requestAnthropicNativeCompaction(
 				model,
 				apiKey,
 				{
-					// The live prompt, not the local summarizer's synthetic system
-					// prompt: kept thinking remains valid only under identical controls.
-					systemPrompt: summaryOptions.remoteSystemPrompt ?? [],
-					messages,
-					tools: summaryOptions.tools,
+					context,
+					filesDueBefore,
 					instructions: buildAnthropicCompactionInstructions(
 						summaryOptions.promptOverride ?? SUMMARIZATION_PROMPT,
 						customInstructions,
@@ -2026,6 +2120,8 @@ export async function compact(
 			content: nativeSummary,
 			...(nativeSignature ? { signature: nativeSignature } : {}),
 			...(filesText ? { filesText } : {}),
+			...(nativeRetainedFiles ? { retainedFiles: nativeRetainedFiles } : {}),
+			exactTail: true,
 			model: model.id,
 			usedTokens: nativeUsedTokens,
 		});

package/src/compaction/entries.ts

@@ -101,8 +101,8 @@ export interface TtsrInjectionEntry extends SessionEntryBase {
 
 export interface SessionInitEntry extends SessionEntryBase {
 	type: "session_init";
-	/** Full system prompt sent to the model */
-	systemPrompt: string;
+	/** System prompt blocks exactly as sent to the model; files written before blocks were kept store one joined string. */
+	systemPrompt: string[] | string;
 	/** Initial task/user message */
 	task: string;
 	/** Tools available to the agent */

package/src/compaction/openai.ts

@@ -90,12 +90,12 @@ interface NormalizedEstimateValue {
 	imageTokens: number;
 }
 
-function normalizeRemoteCompactionEstimateValue(value: unknown): NormalizedEstimateValue {
+function normalizeRemoteCompactionEstimateValue(value: unknown, dropEncrypted = true): NormalizedEstimateValue {
 	if (Array.isArray(value)) {
 		const normalized: unknown[] = [];
 		let imageTokens = 0;
 		for (const item of value) {
-			const result = normalizeRemoteCompactionEstimateValue(item);
+			const result = normalizeRemoteCompactionEstimateValue(item, dropEncrypted);
 			normalized.push(result.value);
 			imageTokens += result.imageTokens;
 		}
@@ -123,14 +123,25 @@ function normalizeRemoteCompactionEstimateValue(value: unknown): NormalizedEstim
 		// Opaque encrypted reasoning/compaction state: its local base64 size far
 		// exceeds what the provider bills, so it stays out of the fit estimate
 		// (same policy as `MessageCountOptions.excludeEncryptedReasoning`).
-		if (key === "encrypted_content" && typeof item === "string") continue;
-		const result = normalizeRemoteCompactionEstimateValue(item);
+		if (dropEncrypted && key === "encrypted_content" && typeof item === "string") continue;
+		const result = normalizeRemoteCompactionEstimateValue(item, dropEncrypted);
 		normalized[key] = result.value;
 		imageTokens += result.imageTokens;
 	}
 	return { value: normalized, imageTokens };
 }
 
+/**
+ * Tokens of stored Responses replacement history. Retained `input_image` parts
+ * count at their image estimate rather than as base64 text; everything else,
+ * opaque compaction state included, counts as serialized.
+ */
+export function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number {
+	const normalized = normalizeRemoteCompactionEstimateValue(items, false);
+	const serialized = stringifyJson(normalized.value);
+	return (serialized === undefined ? 0 : tokenizer.countTokens(serialized)) + normalized.imageTokens;
+}
+
 export interface TrimRemoteCompactionInputResult {
 	input: Array<Record<string, unknown>>;
 	rewrittenOutputs: number;

package/src/image-tokens.ts

@@ -1,4 +1,10 @@
 import type { ImageContent } from "@oh-my-pi/pi-ai";
+import {
+	type ImageSize,
+	type ImageTokenization,
+	imageTokens,
+	resolveImageTokenization,
+} from "@oh-my-pi/pi-catalog/compat/image-tokenization";
 import { parseImageMetadata } from "@oh-my-pi/pi-utils";
 
 /**
@@ -9,63 +15,30 @@ import { parseImageMetadata } from "@oh-my-pi/pi-utils";
  * stayed under the local compaction trigger yet was refused as over-window by
  * the remote probe.
  *
- * Follows OpenAI's patch-based rule (32px patches, a per-detail pixel limit
- * and patch budget, x1.2 multiplier), which is also a close upper estimate for
- * other providers once omp has downscaled the image (≤1568px by default).
+ * Follows the catalog's image rule for the OpenAI Responses wire (GPT-5.5's
+ * 32px patches, a per-detail pixel limit and patch budget, x1.2 multiplier),
+ * which is also a close upper estimate for other providers once omp has
+ * downscaled the image (≤1568px by default).
  */
 
 /** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
 export type ImageDetail = ImageContent["detail"];
 
-export interface ImageSize {
-	width: number;
-	height: number;
-}
-
-const PATCH_PX = 32;
-const PATCH_TOKEN_MULTIPLIER = 1.2;
-
-interface DetailSizing {
-	/** Longest side after the pixel-dimension fit. */
-	maxDimension: number;
-	/** Resizing patch budget, when the detail level defines one. */
-	patchBudget?: number;
-	/** Patches charged when the image size is unknown. */
-	unknownPatches: number;
-}
-
-const LOW_SIZING: DetailSizing = { maxDimension: 512, unknownPatches: 16 * 16 };
-const HIGH_SIZING: DetailSizing = { maxDimension: 2048, patchBudget: 2_500, unknownPatches: 2_500 };
-// `auto` resolves to `original` sizing on current models, so it shares the
-// larger budget rather than risk undercounting.
-const ORIGINAL_SIZING: DetailSizing = { maxDimension: 6_000, patchBudget: 10_000, unknownPatches: 10_000 };
+export type { ImageSize };
 
-function sizingFor(detail: ImageDetail): DetailSizing {
-	if (detail === "low") return LOW_SIZING;
-	if (detail === "high") return HIGH_SIZING;
-	return ORIGINAL_SIZING;
-}
+// Larger than every detail level's pixel limit, so an unknown size charges
+// the level's full patch budget.
+const UNKNOWN_SIZE: ImageSize = { width: 65_535, height: 65_535 };
 
-function countPatches(size: ImageSize, sizing: DetailSizing): number {
-	let { width, height } = size;
-	const longest = Math.max(width, height);
-	if (longest > sizing.maxDimension) {
-		const scale = sizing.maxDimension / longest;
-		width = Math.max(1, Math.round(width * scale));
-		height = Math.max(1, Math.round(height * scale));
-	}
-	const patches = Math.ceil(width / PATCH_PX) * Math.ceil(height / PATCH_PX);
-	const budget = sizing.patchBudget;
-	if (budget === undefined || patches <= budget) return patches;
+let wireRule: ImageTokenization | undefined;
 
-	const shrink = Math.sqrt((PATCH_PX * PATCH_PX * budget) / (width * height));
-	const scaledW = (width * shrink) / PATCH_PX;
-	const scaledH = (height * shrink) / PATCH_PX;
-	const adjusted = shrink * Math.min(Math.floor(scaledW) / scaledW, Math.floor(scaledH) / scaledH);
-	const resizedW = Math.floor(width * adjusted);
-	const resizedH = Math.floor(height * adjusted);
-	if (resizedW <= 0 || resizedH <= 0) return budget;
-	return Math.min(budget, Math.ceil(resizedW / PATCH_PX) * Math.ceil(resizedH / PATCH_PX));
+/** The OpenAI Responses wire's image rule, resolved from the catalog once. */
+function openAiWireRule(): ImageTokenization {
+	if (wireRule) return wireRule;
+	const rule = resolveImageTokenization({ api: "openai-responses" });
+	if (!rule) throw new Error("The catalog has no image-tokenization rule for the openai-responses wire");
+	wireRule = rule;
+	return rule;
 }
 
 /**
@@ -73,9 +46,7 @@ function countPatches(size: ImageSize, sizing: DetailSizing): number {
  * remote URLs, provider file ids) charge the detail level's full patch budget.
  */
 export function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number {
-	const sizing = sizingFor(detail);
-	const patches = size && size.width > 0 && size.height > 0 ? countPatches(size, sizing) : sizing.unknownPatches;
-	return Math.ceil(patches * PATCH_TOKEN_MULTIPLIER);
+	return imageTokens(openAiWireRule(), size && size.width > 0 && size.height > 0 ? size : UNKNOWN_SIZE, detail);
 }
 
 // Enough decoded bytes to reach a JPEG SOF marker behind typical EXIF/ICC

package/src/telemetry.ts

@@ -1790,8 +1790,8 @@ export interface InstrumentedChatSpanOptions {
 	/**
 	 * Tag stamped onto `omp.gen_ai.oneshot.kind`. Values used by the agent:
 	 * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
-	 * `handoff`, `branch_summary`, `image_question`. Free-form to allow callers
-	 * outside this package to add new kinds without bumping the helper.
+	 * `handoff`, `branch_summary`, `image_question`, `skill_description`. Free-form
+	 * to allow callers outside this package to add new kinds without bumping the helper.
 	 */
 	readonly oneshotKind?: string;
 	/** Extra span attributes applied verbatim. */

package/src/tokenizer.ts

@@ -5,7 +5,7 @@ import { materializeString, stringifyJson } from "@oh-my-pi/pi-utils";
 import { LRUCache } from "@oh-my-pi/pi-utils/lru";
 import * as snapcompact from "@oh-my-pi/snapcompact";
 import { isEstimateCacheable, messageEstimateVersion } from "./compaction/message-cache";
-import { estimateImageContentTokens } from "./image-tokens";
+import { base64ImageSize, estimateImageContentTokens } from "./image-tokens";
 import type { AgentMessage } from "./types";
 
 const testEnv = Bun.env.NODE_ENV === "test";
@@ -149,13 +149,15 @@ interface MessageEstimate {
  * Model-aware local token counter. Immutable: the catalog-resolved encoding
  * is fixed at construction, so a cached count can never straddle two
  * encodings. An `Agent` owns one for its active model (swapping the instance
- * when the model's encoding changes); one-shot flows construct their own for
- * the model that will be billed. Known tokenizer families use exact native
- * counts; unknown models keep the fast byte estimate (or o200k when
- * `PI_TOKENIZER_ACCURATE=1`).
+ * when the model's encoding or snapcompact frame pricing changes); one-shot
+ * flows construct their own for the model that will be billed. Known
+ * tokenizer families use exact native counts; unknown models keep the fast
+ * byte estimate (or o200k when `PI_TOKENIZER_ACCURATE=1`).
  */
 export class Tokenizer {
 	readonly #encoding: natives.Encoding | null;
+	readonly #frameBilling: snapcompact.FrameBilling;
+	readonly frameBillingKey: string;
 
 	/** Exact counts only; byte fallbacks remain mode-dependent and uncached. */
 	readonly #nativeCounts = new LRUCache<string, number>({
@@ -174,8 +176,10 @@ export class Tokenizer {
 	 */
 	#estimates = new WeakMap<AgentMessage, MessageEstimate>();
 
-	constructor(model?: Pick<Model, "tokenizer"> | null) {
+	constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null) {
 		this.#encoding = tokenizerEncodingForModel(model);
+		this.#frameBilling = snapcompact.frameBilling(model ?? undefined);
+		this.frameBillingKey = snapcompact.frameBillingKey(this.#frameBilling);
 	}
 
 	get encoding(): natives.Encoding | null {
@@ -332,11 +336,12 @@ export class Tokenizer {
 					if (message.blocks) {
 						for (const block of message.blocks) {
 							if (block.type === "text") fragments.push(block.text);
-							else extra += snapcompact.FRAME_TOKEN_ESTIMATE;
+							else extra += this.#frameTokens(block.data);
 						}
 					} else if (message.images) {
-						// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
-						extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
+						for (const image of message.images) {
+							extra += this.#frameTokens(image.data);
+						}
 					}
 				}
 				break;
@@ -348,4 +353,10 @@ export class Tokenizer {
 		if (fragments.length === 0) return extra;
 		return extra + this.countTokens(fragments);
 	}
+
+	/** One snapcompact frame at the active model's price for its pixel size; unreadable frames cost the ceiling. */
+	#frameTokens(data: string): number {
+		const size = base64ImageSize(data);
+		return size ? snapcompact.frameTokens(this.#frameBilling, size) : snapcompact.FRAME_TOKEN_ESTIMATE;
+	}
 }