pi-codex-compaction 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-09-15
+
+### Added
+
+- Show `[compaction (codex)] Checkpoint saved.` in the TUI after a Codex checkpoint is saved, to distinguish it from standard Pi compaction.
+
+## [0.1.3] - 2026-09-11
+
+### Fixed
+
+- Estimate compaction tokens separately from request bytes so long Codex sessions do not fall back merely because UTF-8 bytes exceed the token budget.
+- Respect request-transform field removals when sizing, restrict warnings to TUI mode, and distinguish preparation failures from transport failures.
+- Preserve the independent 16 MiB request ceiling, count the complete transformed envelope, and reject unavailable context limits.
+- Record safe fallback reasons and numeric size diagnostics in local custom session entries; notify when UI is available without exposing request or provider content.
+
 ## [0.1.2] - 2026-09-11
 
 ### Fixed

package/CONTRIBUTING.md

@@ -29,6 +29,33 @@ Before opening a pull request:
 - Preserve current-model compaction, context bounds, cancellation, HTTPS, and standard Pi fallback behavior.
 - Add a regression test when changing wire parsing, request construction, checkpoint rehydration, or model-switch fallback behavior.
 
+## Token-budget regression and smoke checks
+
+`tests/integration.test.mjs` uses the real Pi compaction hook, serializer, and
+session tree with fake credentials and mocked Responses transport. A synthetic
+long transcript must produce a remote checkpoint even when its UTF-8 bytes
+exceed the numeric token budget. Oversized input must still invoke the standard
+compactor and record a safe fallback reason. A later model request must not
+contain the diagnostic entry. No private session fixtures or live requests are
+needed for these tests.
+
+The token conversion follows Codex's ordinary JSON-item heuristic:
+[byte-to-token estimate](https://github.com/openai/codex/blob/654b0a77d0d2f81aa21f61caf7af4be88fe550bb/codex-rs/utils/string/src/truncate.rs)
+and [history sizing](https://github.com/openai/codex/blob/654b0a77d0d2f81aa21f61caf7af4be88fe550bb/codex-rs/core/src/context_manager/history.rs).
+This package keeps all serialized opaque/image bytes in its estimate instead of
+copying Codex's modality-specific discounts. Never equate bytes and tokens or
+remove the independent wire-size ceiling.
+
+For an offline replay, reconstruct a compaction's discarded history in memory,
+use fake authentication, replace `fetch` with a fixture checkpoint response,
+and call `createRemoteCompaction`. Print only sizes and the success/fallback
+code. Do not save the transcript, request, auth headers, or opaque content.
+
+For an approved live smoke test, follow the procedure in [README.md](./README.md#reference-and-smoke-test).
+Check for `fromHook: true` and `details.kind: "pi-codex-compaction"` on success.
+On fallback, inspect only the reason and counters in the custom diagnostic
+entry. Never inspect or print `encryptedContent`.
+
 ## Code of conduct
 
 This project follows the Contributor Covenant Code of Conduct.

package/README.md

@@ -9,7 +9,7 @@ Keep long Pi sessions usable on OpenAI Codex models by replacing Pi's local summ
 - Retains the normal Codex Responses request envelope, including system instructions, active tool schemas, reasoning settings, prompt-cache fields, and routing fields.
 - Persists Codex's opaque encrypted checkpoint and rehydrates it only for supported Codex requests.
 - Reuses checkpoints only for the same model, trusted endpoint, Codex account, and authentication mode.
-- Bounds input with a UTF-8-aware token estimate, trims tool output when necessary, retries transient failures, and honors cancellation.
+- Bounds input with a Codex-style UTF-8 token estimate and a separate hard byte limit, trims tool output when necessary, retries transient failures, and honors cancellation.
 - Falls back to standard Pi compaction on failure or when custom compaction instructions are requested.
 - Keeps a bounded readable transcript excerpt so switching models or providers remains usable.
 
@@ -35,11 +35,51 @@ pi -e /path/to/pi-mono/packages/pi-codex-compaction
 
 ## Behavior
 
+After a Codex checkpoint is saved, the TUI shows
+`[compaction (codex)] Checkpoint saved.` Pi's built-in `[compaction]` heading
+remains unchanged. The notice is not added to model context or stored in the
+session, and is not replayed on reload. Standard Pi compaction does not show it.
+Print, JSON, and RPC modes receive no extra notification.
+
 When Pi starts compaction on a supported Codex model, the extension sends a streamed Responses request whose `input` contains only discardable history, any compatible prior checkpoint, and a `compaction_trigger` item. The normal request envelope is retained because Codex's compaction path is parity-tested against ordinary Responses requests; this includes the effective system prompt, active tool definitions, reasoning level, prompt-cache fields, and routing fields. The request uses the `remote_compaction_v2` beta feature, and the returned opaque checkpoint and bounded provider usage are stored in the Pi compaction entry. Later requests rehydrate the raw checkpoint only when the model, endpoint, account, and authentication mode match; other providers/models receive the bounded textual fallback instead.
 
 Compaction uses the model active when Pi triggers it. If a session switches from a larger to a smaller model, the remote request is bounded against the new model's context window and tool outputs are reduced before sending. A previous opaque checkpoint is treated as incompatible after a model, endpoint, account, or authentication-mode switch; Pi's readable previous summary is sent instead. If the full request still cannot fit, the extension leaves compaction to Pi's normal implementation.
 
-If the remote request fails, is cancelled, or returns an unexpected response, Pi's standard compaction path runs. Custom compaction instructions also use Pi's standard path because RemoteCompactionV2 has no documented custom-instructions field. The direct checkpoint request is restricted to `https://chatgpt.com`, rejects redirects, limits request/response size, and never decodes or logs `encrypted_content`. No configuration is required.
+If the remote request fails or returns an unexpected response, Pi's standard compaction path runs. Cancellation remains cancelled. Custom compaction instructions also use Pi's standard path because RemoteCompactionV2 has no documented custom-instructions field. The direct checkpoint request is restricted to `https://chatgpt.com`, rejects redirects, limits request/response size, and never decodes or logs `encrypted_content`. No configuration is required.
+
+### Size limits
+
+Input is estimated as `ceil(UTF-8 request bytes / 4)`, with 8,192 tokens reserved
+from the active model's context window. This uses Codex's ordinary-item heuristic,
+not an exact tokenizer. The complete transformed request is counted, including
+system instructions, tool definitions, and routing fields. Opaque checkpoints
+and image data remain counted at their serialized size; they are not decoded or
+discounted. Non-ASCII text uses UTF-8 bytes, not JavaScript string length.
+
+The uncompressed request also has an independent **16 MiB hard limit**. Tool
+outputs are reduced only when one of these limits is exceeded. User messages,
+tool calls, and opaque checkpoints are not removed. If the remaining request
+still cannot fit, or the model's context limit is unknown, standard Pi compaction
+runs. The estimate can differ from the server's token count; a server rejection
+still uses the existing fallback.
+
+### Fallback diagnostics
+
+A fallback on a supported model records a local custom session entry with type
+`pi-codex-compaction:fallback:v1`. It contains `version: 1` and a reason:
+`custom-instructions`, `auth-unavailable`, `request-unavailable`,
+`context-window-unavailable`, `context-limit`, `request-size-limit`, or
+`remote-failed`. Size failures also include estimated tokens, token budget,
+request bytes, byte limit, and the number of tool outputs reduced.
+Unexpected preparation failures use `request-unavailable`; `remote-failed`
+is reserved for failures from the transport call.
+
+No prompt, tool content, encrypted checkpoint, account identifier, credential, or
+raw provider error is included. These entries are not sent to the model. Pi
+shows a warning only in TUI mode when notifications are available; print, JSON,
+and RPC modes get no extra notifications or console output. Unsupported models
+and cancelled attempts do not create fallback diagnostics. Diagnostic storage
+or notification failure does not stop the standard compactor.
 
 ## Development
 
@@ -61,6 +101,7 @@ versioned `pi.events` contracts let cooperating extensions supply it:
 - `pi-codex-compaction:request:v1`: `{ ctx, messages, payload }`, after input
   assembly and before size checks. A listener can replace `payload`. This event
   is not the general `before_provider_request` chain and does not carry auth.
+  Size checks use the transformed envelope, including field removals.
 
 Other extensions' private request changes are not applied automatically.
 Unknown third-party grammar metadata needs cooperation through the tools event.
@@ -78,6 +119,9 @@ API. Async tools and mid-turn steering require upstream Pi support.
 
 For a small live test, load this package and select `openai-codex/gpt-6-astra`.
 Send two short messages, run `/compact`, then ask about the first message.
+Confirm `[compaction (codex)] Checkpoint saved.` appears. Then run
+`/compact Focus on recent work` and confirm the standard-compaction warning
+appears without a Codex success notice.
 Repeat with `/fast on` and `pi-codex-tools` loaded. Check that compaction succeeds,
 the continuation retains context, and session usage includes compaction tokens.
 Use only a temporary file if you test `apply_patch`. Do not generate images.

package/SECURITY.md

@@ -35,4 +35,18 @@ Cooperating local extensions can inspect and transform compaction inputs through
 the documented event bus before size checks. These events contain no credentials.
 They have the same trust level as other installed Pi extensions.
 
+Context sizing uses `ceil(UTF-8 serialized request bytes / 4)` with an 8,192-token
+reserve from the active model's context window. It is an estimate, not a strict
+tokenizer bound. The complete transformed envelope is counted, including opaque
+content at its serialized size. A separate 16 MiB uncompressed request limit is
+enforced before network I/O. The HTTPS, redirect, response-size, checkpoint
+compatibility, and cancellation checks remain independent of token estimation.
+
+Fallback diagnostics store only a fixed reason code and finite non-negative
+size counters in `pi-codex-compaction:fallback:v1` custom session entries.
+These local records never include credentials, account/model identifiers,
+request content, encrypted checkpoints, or raw errors, and do not enter model
+context. No external diagnostic telemetry is added. They use the existing
+session's permissions and retention policy.
+
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development and validation instructions.

package/extensions/index.ts

@@ -7,6 +7,8 @@ import { BETA_FEATURE, getCodexAccountFingerprint } from "../src/codex-wire.js";
 import { reportInstallTelemetry } from "../src/install-telemetry.js";
 import {
   applyRemoteCompactionMarker,
+  COMPACTION_FALLBACK_ENTRY,
+  type CompactionFallback,
   createRemoteCompaction,
   findActiveRemoteCompaction,
   getCodexAuthKind,
@@ -14,12 +16,46 @@ import {
   supportsRemoteCompaction,
 } from "../src/remote-compaction.js";
 
+const FALLBACK_MESSAGES: Record<CompactionFallback["reason"], string> = {
+  "custom-instructions": "custom compaction instructions require the standard compactor",
+  "auth-unavailable": "Codex authentication is unavailable",
+  "request-unavailable": "the Codex request could not be prepared",
+  "context-window-unavailable": "the active model's context limit is unavailable",
+  "context-limit": "the estimated input exceeds the active model's token budget",
+  "request-size-limit": "the request exceeds the 16 MiB byte limit",
+  "remote-failed": "the remote request failed",
+};
+
 export default function piCodexCompaction(pi: ExtensionAPI): void {
   reportInstallTelemetry();
 
   const onBeforeCompact: ExtensionHandler<SessionBeforeCompactEvent, { compaction?: NonNullable<Awaited<ReturnType<typeof createRemoteCompaction>>> }> = async (event, ctx) => {
     if (!supportsRemoteCompaction(ctx.model)) return undefined;
 
+    let reported = false;
+    const reportFallback = (diagnostic: CompactionFallback) => {
+      if (reported || event.signal.aborted) return;
+      reported = true;
+      // No text, model/account identifiers, headers, or provider errors belong
+      // in diagnostics. Custom entries do not enter the model's context.
+      const data: Record<string, unknown> = { version: 1, reason: diagnostic.reason };
+      for (const key of ["estimatedTokens", "tokenBudget", "requestBytes", "byteLimit", "trimmedToolOutputs"] as const) {
+        const value = diagnostic[key];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) data[key] = value;
+      }
+      try {
+        pi.appendEntry(COMPACTION_FALLBACK_ENTRY, data);
+      } catch {
+        // Diagnostics must not prevent the standard compactor from running.
+      }
+      if (ctx.mode === "tui" && ctx.hasUI) {
+        try {
+          ctx.ui.notify(`Codex remote compaction skipped: ${FALLBACK_MESSAGES[diagnostic.reason]}. Using standard Pi compaction.`, "warning");
+        } catch {
+          // Notification failure must not change compaction behavior either.
+        }
+      }
+    };
     try {
       const compaction = await createRemoteCompaction(event, ctx, () => {
         const active = new Set(pi.getActiveTools());
@@ -37,17 +73,27 @@ export default function piCodexCompaction(pi: ExtensionAPI): void {
         // and before network I/O. Never include auth in this event.
         pi.events?.emit("pi-codex-compaction:request:v1", data);
         return data.payload;
-      });
+      }, reportFallback);
       return compaction ? { compaction } : undefined;
     } catch {
-      if (!event.signal.aborted && ctx.hasUI) {
-        ctx.ui.notify("Codex remote compaction failed; using standard Pi compaction.", "warning");
-      }
+      // Transport failures already have a reason; other exceptions mean the
+      // compaction request could not be prepared or processed.
+      reportFallback({ reason: "request-unavailable" });
       return undefined;
     }
   };
   pi.on("session_before_compact", onBeforeCompact);
 
+  pi.on("session_compact", (event, ctx) => {
+    if (ctx.mode !== "tui" || !ctx.hasUI || !event.fromExtension) return;
+    if (!findActiveRemoteCompaction([event.compactionEntry])) return;
+    try {
+      ctx.ui.notify("[compaction (codex)] Checkpoint saved.", "info");
+    } catch {
+      // Display failures must not affect a saved checkpoint or continuation.
+    }
+  });
+
   pi.on("before_provider_headers", (event, ctx) => {
     if (!supportsRemoteCompaction(ctx.model)) return;
     const existing = event.headers["x-codex-beta-features"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-compaction",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Use OpenAI Codex RemoteCompactionV2 for supported Pi sessions.",
   "type": "module",
   "license": "MIT",

package/src/codex-wire.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 
-const MAX_REQUEST_BYTES = 16 * 1024 * 1024;
+export const MAX_COMPACTION_REQUEST_BYTES = 16 * 1024 * 1024;
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 const MAX_ENCRYPTED_CONTENT_CHARS = 2_000_000;
 const REQUEST_HEADER_TIMEOUT_MS = 30_000;
@@ -57,7 +57,7 @@ export async function requestRemoteCompactionWithUsage(
   const accountId = extractAccountId(request.apiKey);
   const headers = buildHeaders(request, accountId);
   const body = JSON.stringify(request.body);
-  if (new TextEncoder().encode(body).byteLength > MAX_REQUEST_BYTES) {
+  if (Buffer.byteLength(body, "utf8") > MAX_COMPACTION_REQUEST_BYTES) {
     throw new Error("Codex compaction request exceeded the size limit");
   }
 

package/src/remote-compaction.ts

@@ -5,6 +5,7 @@ import { convertToLlm, serializeConversation, sessionEntryToContextMessages } fr
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import {
   getCodexAccountFingerprint,
+  MAX_COMPACTION_REQUEST_BYTES,
   requestRemoteCompactionWithUsage,
   resolveCodexResponsesUrl,
   type CodexCompactionUsage,
@@ -12,10 +13,24 @@ import {
 
 export const REMOTE_SUMMARY_MARKER = "[pi-codex-compaction:v1]";
 export const REMOTE_COMPACTION_KIND = "pi-codex-compaction";
+export const COMPACTION_FALLBACK_ENTRY = "pi-codex-compaction:fallback:v1";
+
+export interface CompactionFallback {
+  reason: "custom-instructions" | "auth-unavailable" | "request-unavailable" |
+    "context-window-unavailable" | "context-limit" | "request-size-limit" | "remote-failed";
+  estimatedTokens?: number;
+  tokenBudget?: number;
+  requestBytes?: number;
+  byteLimit?: number;
+  trimmedToolOutputs?: number;
+}
 
 const FALLBACK_SUMMARY_MAX_CHARS = 12_000;
 const MAX_ENCRYPTED_CONTENT_CHARS = 2_000_000;
 const COMPACTION_RESPONSE_RESERVE_TOKENS = 8_192;
+// Codex's ordinary-item estimate uses ceil(UTF-8 bytes / 4), not bytes as
+// tokens. This is a heuristic, not a tokenizer or a context-fit guarantee.
+const APPROX_BYTES_PER_TOKEN = 4;
 const TRUNCATED_TOOL_OUTPUT = "[Tool output omitted from the Codex compaction request to fit the active model context window.]";
 const PI_COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:";
 
@@ -96,6 +111,7 @@ export async function createRemoteCompaction(
   getTools: () => readonly ToolInfoLike[],
   thinkingLevel?: string,
   prepareRequest?: (payload: Record<string, unknown>, messages: readonly AgentMessage[]) => Record<string, unknown>,
+  onFallback?: (diagnostic: CompactionFallback) => void,
 ): Promise<{
   summary: string;
   firstKeptEntryId: string;
@@ -103,17 +119,22 @@ export async function createRemoteCompaction(
   details: RemoteCompactionDetails;
   usage?: Usage;
 } | undefined> {
+  if (event.signal.aborted) return undefined;
+  const skip = (reason: CompactionFallback["reason"]) => {
+    onFallback?.({ reason });
+    return undefined;
+  };
   // Pi's custom focus is part of the standard summarizer contract. The
   // Responses compaction envelope has no documented equivalent, so do not
   // silently discard it.
-  if (event.customInstructions?.trim()) return undefined;
+  if (event.customInstructions?.trim()) return skip("custom-instructions");
 
   const model = ctx.model as CodexModel | undefined;
   if (!model || !supportsRemoteCompaction(model)) return undefined;
 
   const endpoint = resolveCodexResponsesUrl(model.baseUrl);
   const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model as Model<any>);
-  if (!auth.ok || !auth.apiKey) return undefined;
+  if (!auth.ok || !auth.apiKey) return skip("auth-unavailable");
   const accountFingerprint = getCodexAccountFingerprint(auth.apiKey);
   const authKind = getCodexAuthKind(ctx.modelRegistry, model as Model<any>);
 
@@ -135,9 +156,9 @@ export async function createRemoteCompaction(
     event.signal,
     thinkingLevel,
   );
-  if (!providerPayload) return undefined;
+  if (!providerPayload) return skip("request-unavailable");
   const providerInput = providerPayload.input;
-  if (!Array.isArray(providerInput)) return undefined;
+  if (!Array.isArray(providerInput)) return skip("request-unavailable");
   const providerTools = Array.isArray(providerPayload.tools) ? providerPayload.tools : [];
 
   const input = appendCompactionItems(providerInput, event.preparation, compatiblePrevious);
@@ -150,13 +171,14 @@ export async function createRemoteCompaction(
     store: false,
     stream: true,
   });
-  if (!Array.isArray(requestBody.input)) return undefined;
+  if (!Array.isArray(requestBody.input)) return skip("request-unavailable");
   const boundedInput = boundCompactionInput(
     requestBody.input,
     instructions,
     Array.isArray(requestBody.tools) ? requestBody.tools : providerTools,
     model.contextWindow,
     requestBody,
+    onFallback,
   );
   if (!boundedInput) return undefined;
 
@@ -170,6 +192,11 @@ export async function createRemoteCompaction(
       input: boundedInput,
     },
     signal: event.signal,
+  }).catch((error: unknown) => {
+    // Only failures from the transport path receive this reason. Preparation
+    // failures are classified by the extension's outer fallback handler.
+    if (!event.signal.aborted) onFallback?.({ reason: "remote-failed" });
+    throw error;
   });
 
   const fallback = buildFallbackSummary(event.preparation, messages);
@@ -211,16 +238,25 @@ export function boundCompactionInput(
   tools: readonly unknown[],
   contextWindow: number,
   requestPayload?: Record<string, unknown>,
+  onLimit?: (diagnostic: CompactionFallback) => void,
 ): unknown[] | undefined {
-  const budget = Math.max(1, Math.floor(contextWindow - COMPACTION_RESPONSE_RESERVE_TOKENS));
-  // A byte-level bound is conservative when the active model's tokenizer is unavailable:
-  // a token can be represented by a single UTF-8 byte, but not fewer.
-  const budgetBytes = budget;
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+    onLimit?.({ reason: "context-window-unavailable" });
+    return undefined;
+  }
+  const budgetTokens = Math.max(0, Math.floor(contextWindow) - COMPACTION_RESPONSE_RESERVE_TOKENS);
   const bounded = input.map((item) => item);
-  let requestBytes = estimateConservativeBytes(
+  let requestBytes = serializedBytes(
     buildCompactionRequest(requestPayload, bounded, instructions, tools),
   );
-  if (requestBytes <= budgetBytes) return bounded;
+  if (!Number.isFinite(requestBytes)) {
+    onLimit?.({ reason: "request-unavailable" });
+    return undefined;
+  }
+  const fits = () => requestBytes <= MAX_COMPACTION_REQUEST_BYTES &&
+    Math.ceil(requestBytes / APPROX_BYTES_PER_TOKEN) <= budgetTokens;
+  if (fits()) return bounded;
+  let trimmedToolOutputs = 0;
 
   // ponytail: trim tool outputs first; if structural content still exceeds the active model window,
   // let Pi's standard compaction path handle the request instead of inventing a lossy transcript rewrite.
@@ -229,11 +265,24 @@ export function boundCompactionInput(
     const replacement = trimToolOutput(item);
     if (!replacement) continue;
 
-    requestBytes += estimateConservativeBytes(replacement) - estimateConservativeBytes(item);
+    const removedBytes = serializedBytes(item) - serializedBytes(replacement);
+    // A short output can be smaller than the omission notice. Never make a
+    // request larger while trying to fit either limit.
+    if (removedBytes <= 0) continue;
+    requestBytes -= removedBytes;
     bounded[index] = replacement;
-    if (requestBytes <= budgetBytes) return bounded;
+    trimmedToolOutputs++;
+    if (fits()) return bounded;
   }
 
+  onLimit?.({
+    reason: requestBytes > MAX_COMPACTION_REQUEST_BYTES ? "request-size-limit" : "context-limit",
+    estimatedTokens: Math.ceil(requestBytes / APPROX_BYTES_PER_TOKEN),
+    tokenBudget: budgetTokens,
+    requestBytes,
+    byteLimit: MAX_COMPACTION_REQUEST_BYTES,
+    trimmedToolOutputs,
+  });
   return undefined;
 }
 
@@ -486,10 +535,12 @@ function buildCompactionRequest(
   instructions: string,
   tools: readonly unknown[],
 ): Record<string, unknown> {
-  const payload: Record<string, unknown> = requestPayload ? { ...requestPayload } : {};
-  payload.instructions = instructions;
+  // A supplied envelope is authoritative, including fields a listener removed.
+  // Separate defaults apply only to callers without a complete payload.
+  const payload: Record<string, unknown> = requestPayload
+    ? { ...requestPayload }
+    : { instructions, ...(tools.length > 0 ? { tools } : {}) };
   payload.input = input;
-  if (tools.length > 0 || requestPayload && "tools" in requestPayload) payload.tools = tools;
   return payload;
 }
 
@@ -510,10 +561,10 @@ function trimToolOutput(value: unknown): unknown | undefined {
   return undefined;
 }
 
-function estimateConservativeBytes(value: unknown): number {
+function serializedBytes(value: unknown): number {
   try {
     const json = JSON.stringify(value) ?? "";
-    return new TextEncoder().encode(json).byteLength;
+    return Buffer.byteLength(json, "utf8");
   } catch {
     return Number.POSITIVE_INFINITY;
   }