@criogaid/pi-codex-compaction 0.3.0

package/src/remote.ts

@@ -0,0 +1,140 @@
+// Own V2 request adaptation; Pi's model registry owns authentication and provider dispatch.
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Context, Model, ProviderHeaders, ThinkingBudgets, Usage } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { capableModel, deriveEndpoint, normalizeUrl, sameBackend, sameModel, type ProviderIdentity, type RemoteCompactionApi } from "./capability.js";
+import { trimToolOutputsToContextWindow } from "./context-window.js";
+import { estimateImages, type ImageEstimates } from "./image-budget.js";
+import { contextUserItems, type UserItemOrigin } from "./retention-input.js";
+import { CodexCompactionProtocolError, createCompactionCollector, isObject, type JsonObject, prepareRemoteCompactionPayload } from "./protocol.js";
+
+const REMOTE_COMPACTION_FEATURE = "remote_compaction_v2";
+const REQUEST_TIMEOUT_MS = 300_000;
+const MAX_RETRIES = 2;
+const MISSING_PAYLOAD_MESSAGE = "Provider did not expose a request payload";
+
+export interface RemoteCompactionRequest {
+  modelRegistry: Pick<ModelRegistry, "streamSimple">;
+  model: Model<RemoteCompactionApi>;
+  context: Context;
+  reasoning: ThinkingLevel;
+  sessionId: string;
+  thinkingBudgets?: ThinkingBudgets;
+  /** Pi's provider retry setting; Codex caps compaction retries below it. */
+  maxRetries?: number;
+  maxRetryDelayMs?: number;
+  signal: AbortSignal;
+  /** Pi origins of the context's user messages, used to align provider user items with Pi roles. */
+  userItemOrigins?: readonly UserItemOrigin[];
+  priorCheckpoint?: { identity: ProviderIdentity; marker: string; replacementHistory: readonly JsonObject[] };
+  onPrepared?: () => void;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface RemoteCompactionResponse {
+  item: JsonObject;
+  promptInput: JsonObject[];
+  identity: ProviderIdentity;
+  usage: Usage;
+  images: ImageEstimates;
+  /** Whether each promptInput item came from Pi context that Codex would not retain. */
+  contextual: boolean[];
+}
+
+export function mergeRemoteCompactionHeader(headers: ProviderHeaders): ProviderHeaders {
+  const merged = { ...headers };
+  const existingKey = Object.keys(merged).find((key) => key.toLowerCase() === "x-codex-beta-features");
+  const features = new Set(((existingKey ? merged[existingKey] : "") ?? "")
+    .split(",").map((feature) => feature.trim()).filter(Boolean));
+  features.add(REMOTE_COMPACTION_FEATURE);
+  if (existingKey && existingKey !== "x-codex-beta-features") delete merged[existingKey];
+  merged["x-codex-beta-features"] = [...features].join(",");
+  return merged;
+}
+
+function objectItems(input: unknown): JsonObject[] {
+  if (!Array.isArray(input) || !input.every(isObject)) {
+    throw new CodexCompactionProtocolError("Prepared compaction payload has invalid input items");
+  }
+  return input;
+}
+
+export async function requestRemoteCompaction(request: RemoteCompactionRequest): Promise<RemoteCompactionResponse> {
+  request.signal.throwIfAborted();
+  const configured = capableModel(request.model);
+  if (!configured) throw new CodexCompactionProtocolError("Model is not configured for remote compaction");
+  const collector = createCompactionCollector();
+  let sentInput: JsonObject[] | undefined;
+  let identity: ProviderIdentity | undefined;
+  let usage: Usage | undefined;
+  let images: ImageEstimates | undefined;
+  let contextual: boolean[] | undefined;
+  const baseFetch = request.fetch ?? globalThis.fetch;
+  const routedFetch: typeof globalThis.fetch = async (input, init) => {
+    if (!identity) throw new CodexCompactionProtocolError(MISSING_PAYLOAD_MESSAGE);
+    const actual = normalizeUrl(input instanceof Request ? input.url : String(input));
+    const defaultEndpoint = deriveEndpoint(identity.baseUrl, identity.api);
+    if (actual !== defaultEndpoint && actual !== identity.endpoint) {
+      throw new CodexCompactionProtocolError(`Provider requested unexpected compaction endpoint ${actual}`);
+    }
+    const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+    if (method.toUpperCase() !== "POST") throw new CodexCompactionProtocolError("Remote compaction request must use POST");
+    if (actual === identity.endpoint) return baseFetch(input, init);
+    // Endpoint overrides are same-origin HTTP routes; authentication remains assembled by Pi.
+    return input instanceof Request
+      ? baseFetch(new Request(identity.endpoint, new Request(input, init)))
+      : baseFetch(identity.endpoint, init);
+  };
+  const stream = request.modelRegistry.streamSimple(request.model, request.context, {
+    signal: request.signal,
+    // Pi pools WebSockets without comparing handshake headers; V2 needs its feature header on every request.
+    transport: "sse",
+    reasoning: request.reasoning === "off" ? undefined : request.reasoning,
+    thinkingBudgets: request.thinkingBudgets,
+    sessionId: request.sessionId,
+    timeoutMs: REQUEST_TIMEOUT_MS,
+    maxRetries: Math.min(request.maxRetries ?? MAX_RETRIES, MAX_RETRIES),
+    maxRetryDelayMs: request.maxRetryDelayMs,
+    transformHeaders: mergeRemoteCompactionHeader,
+    fetch: routedFetch,
+    onPayload: async (payload, preparedModel) => {
+      if (!sameModel(configured.identity, preparedModel)) {
+        throw new CodexCompactionProtocolError("Provider resolved an unexpected compaction model");
+      }
+      const resolved = capableModel(request.model, preparedModel.baseUrl);
+      if (!resolved) throw new CodexCompactionProtocolError("Resolved provider endpoint is incompatible with remote compaction");
+      identity = resolved.identity;
+      const prior = request.priorCheckpoint?.identity;
+      if (prior && !sameBackend(prior, identity)) {
+        throw new CodexCompactionProtocolError("The active opaque checkpoint belongs to a different resolved provider backend");
+      }
+      const contextItems = contextUserItems(isObject(payload) ? payload.input : undefined, request.userItemOrigins);
+      const payloadItems = isObject(payload) && Array.isArray(payload.input) ? payload.input.filter(isObject) : [];
+      const estimates = await estimateImages([...payloadItems, ...request.priorCheckpoint?.replacementHistory ?? []], request.signal);
+      const prepared = prepareRemoteCompactionPayload(payload, request.priorCheckpoint, (history) => ({
+        ...history,
+        input: trimToolOutputsToContextWindow(objectItems(history.input), history.instructions, request.model.contextWindow, estimates),
+      }));
+      if (prepared.model !== request.model.id) throw new CodexCompactionProtocolError("Provider payload used an unexpected model");
+      const sent = objectItems(prepared.input).slice(0, -1);
+      contextual = sent.map((item) => contextItems.has(item));
+      sentInput = structuredClone(sent);
+      images = estimates;
+      request.onPrepared?.();
+      return prepared;
+    },
+    onProviderStreamEvent: (event) => {
+      request.signal.throwIfAborted();
+      collector.observe(event);
+    },
+  });
+  for await (const event of stream) {
+    request.signal.throwIfAborted();
+    if (event.type === "error") throw new Error(event.error.errorMessage ?? "Codex compaction request failed");
+    if (event.type === "done") usage = event.message.usage;
+  }
+  request.signal.throwIfAborted();
+  if (!sentInput || !identity || !images || !contextual) throw new CodexCompactionProtocolError(MISSING_PAYLOAD_MESSAGE);
+  if (!usage) throw new CodexCompactionProtocolError("Provider stream ended without a completed message");
+  return { item: collector.finish(), promptInput: sentInput, identity, usage, images, contextual };
+}

package/src/request-snapshot.ts

@@ -0,0 +1,225 @@
+// Own ordinary-request prompt and context snapshots that let compaction reuse Pi's projected request prefix,
+// and build compaction's provider context the way Pi 0.99 builds an ordinary request.
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getCurrentSystemMessage, getSystemMessageText, type Context, type Message, type Tool } from "@earendil-works/pi-ai";
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+import { sameBackend, sameModel, type CapableModel, type ProviderIdentity } from "./capability.js";
+import { type CodexCheckpointDetails, fingerprintMessage, projectCheckpointRequest, withoutSystemMessages } from "./checkpoint.js";
+
+const BLOCKED_IMAGE_TEXT = "Image reading is disabled.";
+
+interface SnapshotScope {
+  readonly sessionId: string;
+  readonly identity: ProviderIdentity;
+}
+
+export interface PromptOverride extends SnapshotScope {
+  readonly sourceFingerprint: string;
+  readonly text: string;
+}
+
+export interface ContextSnapshot extends SnapshotScope {
+  readonly sourceFingerprints: readonly string[];
+  readonly messages: readonly AgentMessage[];
+}
+
+/** Snapshots apply only to the session, model, and backend that produced them. */
+export function snapshotFor<T extends SnapshotScope>(
+  snapshot: T | undefined,
+  sessionId: string,
+  target: CapableModel,
+): T | undefined {
+  return snapshot?.sessionId === sessionId && sameModel(snapshot.identity, target.model) &&
+    sameBackend(snapshot.identity, target.identity) ? snapshot : undefined;
+}
+
+function sourceHead(messages: readonly AgentMessage[]) {
+  return getCurrentSystemMessage(convertToLlm([...messages]));
+}
+
+// Collapse source system state only for matching; the snapshot keeps Pi's actual projected transcript for sending.
+function requestSource(messages: readonly AgentMessage[]): AgentMessage[] {
+  const head = sourceHead(messages);
+  const conversation = withoutSystemMessages(messages);
+  return head ? [head, ...conversation] : conversation;
+}
+
+/** Context handlers see only conversation messages; a snapshot needs them to equal the persisted ones. */
+export function matchesConversation(fingerprints: readonly string[], canonical: readonly AgentMessage[]): boolean {
+  const conversation = withoutSystemMessages(canonical);
+  return fingerprints.length === conversation.length &&
+    fingerprints.every((fingerprint, index) => fingerprintMessage(conversation[index]) === fingerprint);
+}
+
+/**
+ * Pi does not expose a run's forced prompt, so a difference between `ctx.getSystemPrompt()` and the
+ * persisted head counts as one. A stale head only drops the override later, because compaction
+ * requires the head fingerprint to match again.
+ */
+export function capturePromptOverride(
+  canonical: readonly AgentMessage[],
+  sessionId: string,
+  target: CapableModel,
+  text: string,
+): PromptOverride | undefined {
+  const head = sourceHead(canonical);
+  if (!head || text === getSystemMessageText(head)) return undefined;
+  return { sessionId, identity: target.identity, sourceFingerprint: fingerprintMessage(head), text };
+}
+
+export function promptOverrideFor(
+  override: PromptOverride | undefined,
+  sessionId: string,
+  target: CapableModel,
+  messages: readonly AgentMessage[],
+): PromptOverride | undefined {
+  const scoped = snapshotFor(override, sessionId, target);
+  const head = scoped && sourceHead(messages);
+  return head && fingerprintMessage(head) === scoped.sourceFingerprint ? scoped : undefined;
+}
+
+export function captureContextSnapshot(
+  sessionId: string,
+  target: CapableModel,
+  source: readonly AgentMessage[],
+  projected: readonly AgentMessage[],
+): ContextSnapshot {
+  return {
+    sessionId,
+    identity: target.identity,
+    sourceFingerprints: requestSource(source).map(fingerprintMessage),
+    messages: structuredClone(projected),
+  };
+}
+
+/** Reuse the projected request while its source is an unchanged prefix, then append newer messages. */
+export function reuseContextSnapshot(messages: AgentMessage[], snapshot: ContextSnapshot | undefined): AgentMessage[] {
+  if (!snapshot) return messages;
+  const source = requestSource(messages);
+  if (source.length < snapshot.sourceFingerprints.length || snapshot.sourceFingerprints.some(
+    (fingerprint, index) => fingerprintMessage(source[index]) !== fingerprint,
+  )) return messages;
+  return [...structuredClone(snapshot.messages), ...source.slice(snapshot.sourceFingerprints.length)];
+}
+
+/** Pi 0.99 applies per-run prompt overrides after context hooks by collapsing system messages into one head. */
+export function applyPromptOverride(messages: Message[], override: PromptOverride): Message[] | undefined {
+  const head = getCurrentSystemMessage(messages);
+  if (!head) return undefined;
+  const { sections: _sections, ...declarations } = head;
+  return [{ ...declarations, content: override.text }, ...withoutSystemMessages(messages)];
+}
+
+/** The snapshots that the latest ordinary request left for compaction. */
+export interface RequestSnapshots {
+  readonly promptOverride?: PromptOverride;
+  readonly context?: ContextSnapshot;
+}
+
+interface TrackedSnapshots {
+  promptOverride?: PromptOverride;
+  pendingSource?: { readonly sessionId: string; readonly fingerprints: readonly string[] };
+  pendingContext?: ContextSnapshot;
+  context?: ContextSnapshot;
+}
+
+/**
+ * Follow one ordinary request through Pi's hooks: `context`, then `context_with_system`, then
+ * `before_provider_request` for each provider attempt. State lives only as long as the Pi process.
+ */
+export class RequestSnapshotTracker {
+  private state: TrackedSnapshots = {};
+
+  /** Forget every snapshot; a compaction that already started keeps the state it captured. */
+  reset(): void {
+    this.state = {};
+  }
+
+  /** The live snapshots a compaction reads; later provider requests may still update them. */
+  current(): RequestSnapshots {
+    return this.state;
+  }
+
+  /** `context`: record the conversation handlers received. Pi clones these messages per request, so hash only for V2. */
+  recordContext(sessionId: string, target: CapableModel | undefined, messages: readonly AgentMessage[]): void {
+    this.state.pendingSource = target ? { sessionId, fingerprints: messages.map(fingerprintMessage) } : undefined;
+    this.state.pendingContext = undefined;
+  }
+
+  /** `context_with_system`: capture Pi's projected request when its source equals the persisted conversation. */
+  recordProjectedRequest(
+    sessionId: string,
+    target: CapableModel | undefined,
+    canonical: () => AgentMessage[],
+    checkpoint: () => CodexCheckpointDetails | undefined,
+    projected: readonly AgentMessage[],
+  ): void {
+    const pending = this.state.pendingSource;
+    this.state.pendingSource = undefined;
+    this.state.pendingContext = undefined;
+    if (!target || pending?.sessionId !== sessionId) return;
+    const messages = canonical();
+    // Request-local, unpersisted messages cannot be aligned safely with the session's future suffix.
+    if (!matchesConversation(pending.fingerprints, messages)) return;
+    const prior = checkpoint();
+    const source = prior ? projectCheckpointRequest(messages, prior) : messages;
+    if (source) this.state.pendingContext = captureContextSnapshot(sessionId, target, source, projected);
+  }
+
+  /** `before_provider_request`: record the effective prompt and publish the pending context. */
+  recordProviderRequest(
+    sessionId: string,
+    target: CapableModel | undefined,
+    canonical: () => AgentMessage[],
+    systemPrompt: () => string,
+  ): void {
+    this.state.promptOverride = target && capturePromptOverride(canonical(), sessionId, target, systemPrompt());
+    // Keep the pending snapshot for retries that prepare a payload without running context hooks again.
+    this.state.context = this.state.pendingContext;
+  }
+}
+
+/** What Pi would declare for an ordinary request whose transcript carries no system messages. */
+export interface RequestDeclarations {
+  readonly blockImages: boolean;
+  readonly systemPrompt: () => string;
+  readonly tools: () => Tool[];
+}
+
+// Mirror Pi 0.99's request-time image blocking, including its deduplicated placeholders.
+function withoutImages(messages: Message[]): Message[] {
+  return messages.map((message) => {
+    if ((message.role !== "user" && message.role !== "toolResult") || !Array.isArray(message.content) ||
+        !message.content.some((part) => part.type === "image")) return message;
+    const content = message.content
+      .map((part) => part.type === "image" ? { type: "text" as const, text: BLOCKED_IMAGE_TEXT } : part)
+      .filter((part, index, parts) => !(part.type === "text" && part.text === BLOCKED_IMAGE_TEXT && index > 0 &&
+        parts[index - 1].type === "text" && (parts[index - 1] as { text: string }).text === BLOCKED_IMAGE_TEXT));
+    return { ...message, content } as Message;
+  });
+}
+
+/**
+ * Build compaction's provider context from the current transcript and the snapshots bound to this
+ * session, model, and backend. Pi 0.99 transcripts declare the prompt and tools through system
+ * messages, as ordinary requests do; `messages` is the transcript actually sent.
+ */
+export function compactionRequest(
+  snapshots: RequestSnapshots,
+  sessionId: string,
+  target: CapableModel,
+  current: AgentMessage[],
+  declarations: RequestDeclarations,
+): { readonly context: Context; readonly messages: AgentMessage[] } {
+  const override = promptOverrideFor(snapshots.promptOverride, sessionId, target, current);
+  const messages = reuseContextSnapshot(current, snapshotFor(snapshots.context, sessionId, target));
+  const converted = convertToLlm(messages);
+  const llmMessages = declarations.blockImages ? withoutImages(converted) : converted;
+  const overridden = override && applyPromptOverride(llmMessages, override);
+  if (overridden) return { context: { messages: overridden }, messages };
+  if (llmMessages.some((message) => message.role === "system")) return { context: { messages: llmMessages }, messages };
+  return {
+    context: { systemPrompt: declarations.systemPrompt(), messages: llmMessages, tools: declarations.tools() },
+    messages,
+  };
+}

package/src/retention-input.ts

@@ -0,0 +1,146 @@
+// Adapt Responses messages to Codex rust-v0.159.2's metadata-free retained groups.
+// Context markers mirror core/src/context; XML is parsed at this boundary, not by the budget core.
+// Pi message origins stand in for Codex's separate contextual messages where Pi merges them into user items.
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { convertToLlm, parseSkillBlock } from "@earendil-works/pi-coding-agent";
+import { SaxesParser } from "saxes";
+import { historyGroups, inputText, matchesMarkedText, trimWhiteSpace } from "./history-groups.js";
+import { estimateImages, type ImageEstimates } from "./image-budget.js";
+import { isObject, type JsonObject } from "./protocol.js";
+import type { RetentionInput } from "./retention.js";
+
+const CONTEXT_MARKERS: readonly (readonly [string, string])[] = [
+  ["# AGENTS.md instructions", "</INSTRUCTIONS>"],
+  ["<environment_context>", "</environment_context>"],
+  ["<agent_message_board_notification>", "</agent_message_board_notification>"],
+  ["<skill>", "</skill>"],
+  ["<user_shell_command>", "</user_shell_command>"],
+  ["<turn_aborted>", "</turn_aborted>"],
+  ["<subagent_notification>", "</subagent_notification>"],
+  ["<recommended_plugins>", "</recommended_plugins>"],
+];
+const EXTERNAL_PREFIX = "<external_";
+
+function contextual(text: string): boolean {
+  if (CONTEXT_MARKERS.some((markers) => matchesMarkedText(text, markers))) return true;
+  if (text.startsWith(EXTERNAL_PREFIX)) {
+    const delimiter = text.indexOf(">", EXTERNAL_PREFIX.length);
+    if (delimiter >= 0 && text.endsWith(`</external_${text.slice(EXTERNAL_PREFIX.length, delimiter)}>`)) return true;
+  }
+  if (text.startsWith("<goal_context>") && text.endsWith("</goal_context>")) return true;
+  if (/^<codex_internal_context source="[a-z][a-z0-9_]*">[\s\S]*<\/codex_internal_context>$/.test(text)) return true;
+  return (text.startsWith("Warning: apply_patch was requested via ") &&
+    text.endsWith("Use the apply_patch tool instead of exec_command.")) ||
+    text.startsWith("Warning: The maximum number of unified exec processes you can keep open is") ||
+    text.startsWith("Warning: Your account was flagged for potentially high-risk cyber activity");
+}
+
+// quick-xml's struct deserializer accepts any root name and reads only the first root.
+// A nonempty hook_run_id and exactly one direct text field are required; nested fields are ignored.
+// Known deviation: saxes rejects some input quick-xml 0.41 accepts (a leading XML declaration or
+// DOCTYPE, prefixed attributes, a raw "<" in attribute values, "]]>" in text, invalid names, and
+// control characters). Such text is classified as ordinary user text, never the reverse; retention
+// differs only when it shares a message with other parts.
+function hookPrompt(text: string): boolean {
+  if (!text.includes("hook_run_id")) return false;
+  const parser = new SaxesParser({ fragment: true });
+  let depth = 0;
+  let finished = false;
+  let rootEnd = Infinity;
+  let invalid = false;
+  let hookRunId = "";
+  let textFields = 0;
+  let previousChild = false;
+  parser.on("error", () => { if (parser.position <= rootEnd) invalid = true; });
+  parser.on("opentag", (tag) => {
+    if (finished) return;
+    if (depth === 0) hookRunId = typeof tag.attributes.hook_run_id === "string" ? tag.attributes.hook_run_id : "";
+    if (depth === 1) previousChild = true;
+    depth++;
+  });
+  const recordText = (value: string) => {
+    if (finished) return;
+    if (depth === 0 && value.trim()) invalid = true;
+    if (depth === 1 && value.replace(/^[\x20\t\r\n]+|[\x20\t\r\n]+$/g, "")) {
+      if (textFields === 0 || previousChild) textFields++;
+      previousChild = false;
+    }
+  };
+  parser.on("text", recordText);
+  parser.on("cdata", recordText);
+  parser.on("closetag", () => {
+    if (!finished && --depth === 0) { finished = true; rootEnd = parser.position; }
+  });
+  parser.write(text).close();
+  return finished && !invalid && trimWhiteSpace(hookRunId).length > 0 && textFields === 1;
+}
+function isUserMessage(item: JsonObject): boolean {
+  if ((item.type !== undefined && item.type !== "message") || item.role !== "user" || !Array.isArray(item.content)) return false;
+  let hasContext = false;
+  let hasHook = false;
+  let allHookOrContext = true;
+  for (const part of item.content) {
+    const text = inputText(part);
+    if (text === undefined) { allHookOrContext = false; continue; }
+    const hook = hookPrompt(text);
+    const context = contextual(text);
+    hasContext ||= context || hook;
+    hasHook ||= hook;
+    allHookOrContext &&= hook || context;
+  }
+  return (hasHook && allHookOrContext) || !hasContext;
+}
+/** Pi sends user shell commands and hidden extension messages as user items; Codex treats them as context. */
+export type UserItemOrigin = "user" | "context";
+
+function origin(message: AgentMessage): UserItemOrigin {
+  return message.role === "bashExecution" || (message.role === "custom" && !message.display) ? "context" : "user";
+}
+
+/** Origins of the provider's user items, in order; Pi's Responses adapter skips empty content arrays. */
+export function userItemOrigins(messages: readonly AgentMessage[]): UserItemOrigin[] {
+  return messages.flatMap((message) => convertToLlm([message])
+    .filter((llm) => llm.role === "user" && (typeof llm.content === "string" || llm.content.length > 0))
+    .map(() => origin(message)));
+}
+
+function isUserItem(item: JsonObject): boolean {
+  return (item.type === undefined || item.type === "message") && item.role === "user";
+}
+
+/** Match provider user items to Pi origins; a changed user sequence falls back to text classification. */
+export function contextUserItems(input: unknown, origins: readonly UserItemOrigin[] | undefined): ReadonlySet<JsonObject> {
+  const users = Array.isArray(input) ? input.filter(isObject).filter(isUserItem) : [];
+  if (!origins || users.length !== origins.length) return new Set();
+  return new Set(users.filter((_, index) => origins[index] === "context"));
+}
+
+// Pi prepends an expanded skill to the user's text; Codex keeps the skill as a separate contextual message.
+function withoutSkillBlocks(item: JsonObject): JsonObject | undefined {
+  if (!Array.isArray(item.content)) return item;
+  let changed = false;
+  const content = item.content.flatMap((part: unknown) => {
+    if (!isObject(part) || part.type !== "input_text" || typeof part.text !== "string") return [part];
+    const skill = parseSkillBlock(part.text);
+    if (!skill) return [part];
+    changed = true;
+    return skill.userMessage ? [{ ...part, text: skill.userMessage }] : [];
+  });
+  if (!changed) return item;
+  return content.length ? { ...item, content } : undefined;
+}
+
+export async function prepareRetention(
+  input: readonly JsonObject[],
+  signal: AbortSignal,
+  options: { images?: ImageEstimates; contextual?: readonly boolean[] } = {},
+): Promise<RetentionInput> {
+  const contextual = new Set(input.filter((_, index) => options.contextual?.[index]));
+  const groups = historyGroups(input).flatMap((group) => {
+    signal.throwIfAborted();
+    if (contextual.has(group.source) || !isUserMessage(group.source)) return [];
+    const source = withoutSkillBlocks(group.source);
+    return source ? [{ ...group, source }] : [];
+  });
+  return { groups, images: options.images ?? await estimateImages(groups.map((group) => group.source), signal) };
+}

package/src/retention.ts

@@ -0,0 +1,108 @@
+// Own Codex V2 retention for Pi message items, including its enabled image-budget policy.
+// Reference: openai/codex rust-v0.159.2, compact_remote_v2.rs and compact_remote_v2_images.rs.
+import type { HistoryGroup } from "./history-groups.js";
+import type { ImageEstimates } from "./image-budget.js";
+import { isInputImage, type JsonObject } from "./protocol.js";
+import { approximateTokenCount, approximateTokensFromBytes, truncateTextToTokenBudget } from "./text-budget.js";
+
+export const RETAINED_MESSAGE_TOKEN_BUDGET = 64_000;
+const IMAGE_OPEN_TAG = "<image>";
+const IMAGE_CLOSE_TAG = "</image>";
+const LOCAL_IMAGE_OPEN_PREFIX = "<image name=";
+
+type TextPart = JsonObject & { type: "input_text" | "output_text"; text: string };
+export interface RetentionInput {
+  readonly groups: readonly HistoryGroup[];
+  readonly images: ImageEstimates;
+}
+function isTextPart(part: unknown): part is TextPart {
+  return typeof part === "object" && part !== null && "type" in part &&
+    (part.type === "input_text" || part.type === "output_text") &&
+    "text" in part && typeof part.text === "string";
+}
+function isTag(part: unknown, tag: string): boolean {
+  return isTextPart(part) && part.type === "input_text" && part.text === tag;
+}
+function isImageOpenTag(part: unknown): boolean {
+  return isTag(part, IMAGE_OPEN_TAG) || (isTextPart(part) && part.type === "input_text" &&
+    part.text.startsWith(LOCAL_IMAGE_OPEN_PREFIX) && part.text.endsWith(">"));
+}
+function partTokenCount(part: unknown, images: ImageEstimates): number {
+  if (isTextPart(part)) return approximateTokenCount(part.text);
+  return isInputImage(part) ? approximateTokensFromBytes(images.bytes(part)) : 0;
+}
+function textTokenCount(item: JsonObject): number {
+  return Array.isArray(item.content)
+    ? item.content.reduce((tokens: number, part: unknown) => tokens + (isTextPart(part) ? approximateTokenCount(part.text) : 0), 0)
+    : 0;
+}
+function truncateTextMessage(item: JsonObject, maxTokens: number): JsonObject | undefined {
+  if (!Array.isArray(item.content)) return undefined;
+  let remaining = maxTokens;
+  const content: unknown[] = [];
+  for (const part of item.content) {
+    if (!isTextPart(part)) { content.push(part); continue; }
+    if (remaining === 0) continue;
+    const tokenCount = approximateTokenCount(part.text);
+    const text = tokenCount <= remaining ? part.text : truncateTextToTokenBudget(part.text, remaining);
+    remaining = Math.max(0, remaining - tokenCount);
+    if (text) content.push({ ...part, text });
+  }
+  return content.length ? { ...item, content } : undefined;
+}
+function truncateImageMessage(item: JsonObject, maxTokens: number, images: ImageEstimates): JsonObject | undefined {
+  if (!Array.isArray(item.content)) return undefined;
+  const pending: unknown[] = [...item.content];
+  const reversed: unknown[] = [];
+  let remaining = maxTokens;
+  while (pending.length) {
+    const last = pending.length - 1;
+    const imageIndex = isInputImage(pending[last]) ? last
+      : isTag(pending[last], IMAGE_CLOSE_TAG) && last > 0 && isInputImage(pending[last - 1]) ? last - 1 : undefined;
+    if (imageIndex !== undefined) {
+      const start = imageIndex > 0 && isImageOpenTag(pending[imageIndex - 1]) ? imageIndex - 1 : imageIndex;
+      const tokens = pending.slice(start).reduce((sum: number, part: unknown) => sum + partTokenCount(part, images), 0);
+      const fits = tokens <= remaining;
+      remaining = fits ? remaining - tokens : 0;
+      if (fits) reversed.push(...pending.slice(start).reverse());
+      pending.length = start;
+      continue;
+    }
+    const part = pending.pop();
+    if (!isTextPart(part)) { reversed.push(part); continue; }
+    if (!remaining) continue;
+    const tokens = approximateTokenCount(part.text);
+    const text = tokens <= remaining ? part.text : truncateTextToTokenBudget(part.text, remaining);
+    remaining = Math.max(0, remaining - tokens);
+    if (text) reversed.push({ ...part, text });
+  }
+  return reversed.length ? { ...item, content: reversed.reverse() } : undefined;
+}
+
+/** Keep newest user groups within Codex's fixed budget, preserving image/label groups atomically. */
+export function buildReplacementHistory({ groups, images }: RetentionInput, compactionItem: JsonObject): JsonObject[] {
+  let remaining = RETAINED_MESSAGE_TOKEN_BUDGET;
+  const reversed: JsonObject[] = [];
+  for (let index = groups.length - 1; index >= 0 && remaining > 0; index--) {
+    const { source, notice } = groups[index];
+    const noticeTokens = notice ? Math.max(1, textTokenCount(notice)) : 0;
+    const sourceTokens = Math.max(1, Array.isArray(source.content)
+      ? source.content.reduce((sum: number, part: unknown) => sum + partTokenCount(part, images), 0) : 0);
+    const hasImages = Array.isArray(source.content) && source.content.some(isInputImage);
+    if (sourceTokens + noticeTokens <= remaining) {
+      if (notice) reversed.push(notice);
+      reversed.push(source);
+      remaining -= sourceTokens + noticeTokens;
+    } else if (remaining > noticeTokens) {
+      const budget = remaining - noticeTokens;
+      if (hasImages) remaining = 0;
+      const truncated = hasImages ? truncateImageMessage(source, budget, images) : truncateTextMessage(source, budget);
+      if (!truncated) continue;
+      if (notice) reversed.push(notice);
+      reversed.push(truncated);
+      remaining = 0;
+    } else if (hasImages) remaining = 0;
+  }
+  // The collector validated the item; checkpoint parsing validates it again on persistence.
+  return structuredClone([...reversed.reverse(), compactionItem]);
+}

package/src/text-budget.ts

@@ -0,0 +1,36 @@
+// Own Codex's approximate token counting and UTF-8 middle truncation.
+const APPROX_BYTES_PER_TOKEN = 4;
+
+export function approximateTokensFromBytes(bytes: number): number {
+  return bytes <= 0 ? 0 : Math.ceil(bytes / APPROX_BYTES_PER_TOKEN);
+}
+export function approximateBytesForTokens(tokens: number): number {
+  return tokens * APPROX_BYTES_PER_TOKEN;
+}
+export function approximateTokenCount(text: string): number {
+  return approximateTokensFromBytes(Buffer.byteLength(text, "utf8"));
+}
+export function truncateTextToTokenBudget(text: string, maxTokens: number): string {
+  const budgetBytes = maxTokens * APPROX_BYTES_PER_TOKEN;
+  const totalBytes = Buffer.byteLength(text, "utf8");
+  if (totalBytes <= budgetBytes) return text;
+  const prefixBudgetBytes = Math.floor(budgetBytes / 2);
+  const suffixStartBytes = totalBytes - (budgetBytes - prefixBudgetBytes);
+  // Track UTF-16 indices of the character boundaries so both ends are sliced once.
+  let offsetBytes = 0;
+  let index = 0;
+  let prefixEnd = 0;
+  let suffixStart = text.length;
+  for (const character of text) {
+    const endBytes = offsetBytes + Buffer.byteLength(character, "utf8");
+    if (endBytes <= prefixBudgetBytes) prefixEnd = index + character.length;
+    else if (offsetBytes >= suffixStartBytes) {
+      suffixStart = index;
+      break;
+    }
+    offsetBytes = endBytes;
+    index += character.length;
+  }
+  const marker = `…${approximateTokensFromBytes(totalBytes - budgetBytes)} tokens truncated…`;
+  return `${text.slice(0, prefixEnd)}${marker}${text.slice(suffixStart)}`;
+}