pi-codex-compaction 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-11
+
+### Fixed
+
+- Preserve pi-codex-tools grammar metadata and custom-tool history during remote compaction.
+- Honor pi-fast on direct compaction requests through a public event-bus contract.
+- Include cache writes and standard Pi compaction usage in session totals.
+- Restrict endpoint paths and ports; merge beta features and honor null auth headers.
+- Avoid I/O after pre-cancellation, bound total request time, and close completed SSE streams promptly.
+
 ## [0.1.1] - 2026-08-06
 
 ### Fixed

package/README.md

@@ -13,7 +13,7 @@ Keep long Pi sessions usable on OpenAI Codex models by replacing Pi's local summ
 - 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.
 
-The current Codex catalog includes models such as `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`. Capability detection follows the provider/API contract (`openai-codex` + `openai-codex-responses`) rather than a brittle model-name list.
+The current Codex catalog includes `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`. Capability detection follows the provider/API contract (`openai-codex` + `openai-codex-responses`) rather than a brittle model-name list. Use Pi 0.85.1 or later.
 
 ## Installation
 
@@ -43,6 +43,45 @@ If the remote request fails, is cancelled, or returns an unexpected response, Pi
 
 ## Development
 
+### Other Codex extensions
+
+With `pi-fast` installed, direct compaction requests use the current Fast toggle.
+With `pi-codex-tools` installed, `apply_patch` keeps its raw grammar definition,
+custom-tool calls, and custom-tool results during compaction. Neither package is
+required. No package reads a private Pi tool registry.
+With `pi-openai-reasoning` installed, verified Astra requests keep the original
+request effort and receive the current effort as a configuration update.
+Failed compaction does not change saved reasoning state.
+
+Pi 0.85.1 does not expose grammar metadata in `getAllTools()`. Two synchronous,
+versioned `pi.events` contracts let cooperating extensions supply it:
+
+- `pi-codex-compaction:tools:v1`: `{ model, tools }`, before provider serialization.
+  A tool owner can attach its own `constrainedSampling` metadata.
+- `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.
+
+Other extensions' private request changes are not applied automatically.
+Unknown third-party grammar metadata needs cooperation through the tools event.
+The checkpoint entry includes standard Pi `usage`, including cache reads and
+cache writes, as well as the original bounded token counters in `details`.
+Costs follow Pi's catalog estimates. They are not a ChatGPT subscription bill.
+
+### Reference and smoke test
+
+Behavior was checked against `openai/codex` commit
+`654b0a77d0d2f81aa21f61caf7af4be88fe550bb` (2026-09-11), notably
+`core/src/compact_remote_v2{,_attempt}.rs`. No Codex code was copied.
+RemoteCompactionV2 is a changing Codex protocol, not the public `/responses/compact`
+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.
+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.
+
 ```bash
 npm install
 npm run -w packages/pi-codex-compaction check

package/SECURITY.md

@@ -25,4 +25,14 @@ The extension bounds request, compaction input, and response size, validates the
 
 The extension never logs prompts, conversation contents, credentials, authorization headers, or raw provider responses. Install/update telemetry is best-effort and sends only package/version/runtime metadata; it can be disabled with `PI_OFFLINE=1`, `PI_TELEMETRY=0`, or Pi's `enableInstallTelemetry: false` setting.
 
+Direct requests allow only the official `/backend-api/codex/responses` endpoint
+on the default HTTPS port, without query strings or fragments. Total request
+time is limited to five minutes, including retries. Completed streams are closed
+without waiting for a server disconnect. A pre-aborted request does no network I/O.
+Null auth headers remove matching model headers; beta features are merged.
+
+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.
+
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development and validation instructions.

package/extensions/index.ts

@@ -23,10 +23,21 @@ export default function piCodexCompaction(pi: ExtensionAPI): void {
     try {
       const compaction = await createRemoteCompaction(event, ctx, () => {
         const active = new Set(pi.getActiveTools());
-        return pi.getAllTools()
-          .filter((tool) => active.has(tool.name))
-          .map(({ name, description, parameters }) => ({ name, description, parameters }));
-      }, pi.getThinkingLevel?.());
+        const data = {
+          model: ctx.model,
+          tools: pi.getAllTools().filter((tool) => active.has(tool.name)),
+        };
+        // Pi's public ToolInfo omits constrainedSampling. Tool owners can supply
+        // it here without exposing executors or inspecting private registries.
+        pi.events?.emit("pi-codex-compaction:tools:v1", data);
+        return data.tools;
+      }, pi.getThinkingLevel?.(), (payload, messages) => {
+        const data = { payload, messages, ctx };
+        // Synchronous bus contract: apply pure request transforms before bounds
+        // and before network I/O. Never include auth in this event.
+        pi.events?.emit("pi-codex-compaction:request:v1", data);
+        return data.payload;
+      });
       return compaction ? { compaction } : undefined;
     } catch {
       if (!event.signal.aborted && ctx.hasUI) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-compaction",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Use OpenAI Codex RemoteCompactionV2 for supported Pi sessions.",
   "type": "module",
   "license": "MIT",
@@ -52,10 +52,10 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.82.1",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
-    "@types/node": "^26.1.2",
-    "tsx": "^4.23.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^26.2.0",
+    "tsx": "^4.23.5",
     "typescript": "^7.0.2"
   },
   "publishConfig": {

package/src/codex-wire.ts

@@ -5,6 +5,7 @@ const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
 const MAX_ENCRYPTED_CONTENT_CHARS = 2_000_000;
 const REQUEST_HEADER_TIMEOUT_MS = 30_000;
 const REQUEST_IDLE_TIMEOUT_MS = 120_000;
+const REQUEST_TOTAL_TIMEOUT_MS = 300_000;
 const MAX_RETRIES = 2;
 const RETRY_BASE_DELAY_MS = 200;
 const MAX_RETRY_DELAY_MS = 30_000;
@@ -16,10 +17,10 @@ export interface CodexCompactionRequest {
   model: {
     id: string;
     baseUrl: string;
-    headers?: Record<string, string>;
+    headers?: Record<string, string | null>;
   };
   apiKey: string;
-  authHeaders?: Record<string, string>;
+  authHeaders?: Record<string, string | null>;
   sessionId?: string;
   body: Record<string, unknown>;
   signal?: AbortSignal;
@@ -30,12 +31,14 @@ export interface CodexCompactionUsage {
   outputTokens?: number;
   totalTokens?: number;
   cachedInputTokens?: number;
+  cacheWriteInputTokens?: number;
   reasoningTokens?: number;
 }
 
 export interface CodexCompactionResult {
   encryptedContent: string;
   usage?: CodexCompactionUsage;
+  serviceTier?: "default" | "priority" | "flex";
 }
 
 /**
@@ -49,6 +52,7 @@ export async function requestRemoteCompaction(request: CodexCompactionRequest):
 export async function requestRemoteCompactionWithUsage(
   request: CodexCompactionRequest,
 ): Promise<CodexCompactionResult> {
+  request.signal?.throwIfAborted();
   const endpoint = resolveCodexResponsesUrl(request.model.baseUrl);
   const accountId = extractAccountId(request.apiKey);
   const headers = buildHeaders(request, accountId);
@@ -60,6 +64,7 @@ export async function requestRemoteCompactionWithUsage(
   const requestState = requestSignal(request.signal);
   try {
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      requestState.signal.throwIfAborted();
       requestState.startAttempt();
 
       try {
@@ -116,8 +121,14 @@ export function resolveCodexResponsesUrl(baseUrl: string): string {
   if (url.username || url.password) {
     throw new Error("Codex compaction endpoint must not contain URL credentials");
   }
+  if (url.port || url.search || url.hash) {
+    throw new Error("Codex compaction endpoint must use the default port without query or fragment");
+  }
 
   const path = url.pathname.replace(/\/+$/, "");
+  if (!["/backend-api", "/backend-api/codex", "/backend-api/codex/responses"].includes(path)) {
+    throw new Error("Codex compaction endpoint must use the Codex Responses path");
+  }
   if (path.endsWith("/codex/responses")) {
     return url.toString();
   }
@@ -140,14 +151,20 @@ export function parseCompactionSseResult(sse: string): CodexCompactionResult {
 
 function buildHeaders(request: CodexCompactionRequest, accountId: string): Headers {
   const headers = new Headers();
-  for (const [name, value] of Object.entries(request.model.headers ?? {})) headers.set(name, value);
-  for (const [name, value] of Object.entries(request.authHeaders ?? {})) headers.set(name, value);
+  for (const [name, value] of Object.entries(request.model.headers ?? {})) {
+    if (value !== null) headers.set(name, value);
+  }
+  for (const [name, value] of Object.entries(request.authHeaders ?? {})) {
+    if (value !== null) headers.set(name, value);
+    else headers.delete(name);
+  }
 
   headers.set("Authorization", `Bearer ${request.apiKey}`);
   headers.set("chatgpt-account-id", accountId);
   headers.set("originator", "pi");
   headers.set("OpenAI-Beta", "responses=experimental");
-  headers.set("x-codex-beta-features", BETA_FEATURE);
+  const features = headers.get("x-codex-beta-features")?.split(",").map((part) => part.trim()).filter(Boolean) ?? [];
+  headers.set("x-codex-beta-features", [...new Set([...features, BETA_FEATURE])].join(","));
   headers.set("accept", "text/event-stream");
   headers.set("content-type", "application/json");
 
@@ -208,6 +225,7 @@ async function readCompactionSse(
         throw new CodexCompactionError("Codex compaction response exceeded the size limit", false);
       }
       parser.push(decoder.decode(value, { stream: true }));
+      if (parser.isComplete) return parser.finish();
     }
     parser.push(decoder.decode());
     return parser.finish();
@@ -227,6 +245,11 @@ class CompactionSseParser {
   private status: string | undefined;
   private compactionItems: Array<string | undefined> = [];
   private usage: CodexCompactionUsage | undefined;
+  private serviceTier: CodexCompactionResult["serviceTier"];
+
+  get isComplete(): boolean {
+    return this.completed;
+  }
 
   push(chunk: string): void {
     this.buffer += chunk;
@@ -262,6 +285,7 @@ class CompactionSseParser {
     return {
       encryptedContent,
       ...(this.usage ? { usage: this.usage } : {}),
+      ...(this.serviceTier ? { serviceTier: this.serviceTier } : {}),
     };
   }
 
@@ -294,6 +318,8 @@ class CompactionSseParser {
       const response = isRecord(event.response) ? event.response : undefined;
       this.status = typeof response?.status === "string" ? response.status : undefined;
       this.usage = parseUsage(response?.usage ?? event.usage);
+      const tier = response?.service_tier;
+      this.serviceTier = tier === "default" || tier === "priority" || tier === "flex" ? tier : undefined;
 
       // Codex emits output_item.done before response.completed. Retain this
       // fallback for compact Responses implementations that only return the
@@ -331,12 +357,14 @@ function parseUsage(value: unknown): CodexCompactionUsage | undefined {
   const inputDetails = isRecord(value.input_tokens_details) ? value.input_tokens_details : undefined;
   const outputDetails = isRecord(value.output_tokens_details) ? value.output_tokens_details : undefined;
   const cachedInputTokens = finiteNonNegativeNumber(inputDetails?.cached_tokens);
+  const cacheWriteInputTokens = finiteNonNegativeNumber(inputDetails?.cache_write_tokens);
   const reasoningTokens = finiteNonNegativeNumber(outputDetails?.reasoning_tokens);
   if (
     inputTokens === undefined &&
     outputTokens === undefined &&
     totalTokens === undefined &&
     cachedInputTokens === undefined &&
+    cacheWriteInputTokens === undefined &&
     reasoningTokens === undefined
   ) {
     return undefined;
@@ -346,6 +374,7 @@ function parseUsage(value: unknown): CodexCompactionUsage | undefined {
     ...(outputTokens !== undefined ? { outputTokens } : {}),
     ...(totalTokens !== undefined ? { totalTokens } : {}),
     ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheWriteInputTokens !== undefined ? { cacheWriteInputTokens } : {}),
     ...(reasoningTokens !== undefined ? { reasoningTokens } : {}),
   };
 }
@@ -428,6 +457,10 @@ interface RequestSignal {
 
 function requestSignal(signal: AbortSignal | undefined): RequestSignal {
   const controller = new AbortController();
+  const totalTimeout = setTimeout(
+    () => controller.abort(new Error("Codex compaction request exceeded the total time limit")),
+    REQUEST_TOTAL_TIMEOUT_MS,
+  );
   let headerTimeout: ReturnType<typeof setTimeout> | undefined;
   let idleTimeout: ReturnType<typeof setTimeout> | undefined;
 
@@ -468,6 +501,7 @@ function requestSignal(signal: AbortSignal | undefined): RequestSignal {
     },
     touch,
     cleanup: () => {
+      clearTimeout(totalTimeout);
       clearTimers();
       signal?.removeEventListener("abort", onAbort);
     },

package/src/remote-compaction.ts

@@ -1,5 +1,5 @@
 import { stream as captureProviderPayload } from "@earendil-works/pi-ai/compat";
-import type { Model, Tool } from "@earendil-works/pi-ai";
+import { calculateCost, type Model, type Tool, type Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext, SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
 import { convertToLlm, serializeConversation, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
@@ -95,11 +95,13 @@ export async function createRemoteCompaction(
   ctx: ExtensionContext,
   getTools: () => readonly ToolInfoLike[],
   thinkingLevel?: string,
+  prepareRequest?: (payload: Record<string, unknown>, messages: readonly AgentMessage[]) => Record<string, unknown>,
 ): Promise<{
   summary: string;
   firstKeptEntryId: string;
   tokensBefore: number;
   details: RemoteCompactionDetails;
+  usage?: Usage;
 } | undefined> {
   // Pi's custom focus is part of the standard summarizer contract. The
   // Responses compaction envelope has no documented equivalent, so do not
@@ -139,16 +141,20 @@ export async function createRemoteCompaction(
   const providerTools = Array.isArray(providerPayload.tools) ? providerPayload.tools : [];
 
   const input = appendCompactionItems(providerInput, event.preparation, compatiblePrevious);
-  const requestBody = {
+  const requestBody = prepareRequest?.({
     ...providerPayload,
+    input,
+  }, messages) ?? { ...providerPayload, input };
+  Object.assign(requestBody, {
     model: model.id,
     store: false,
     stream: true,
-  };
+  });
+  if (!Array.isArray(requestBody.input)) return undefined;
   const boundedInput = boundCompactionInput(
-    input,
+    requestBody.input,
     instructions,
-    providerTools,
+    Array.isArray(requestBody.tools) ? requestBody.tools : providerTools,
     model.contextWindow,
     requestBody,
   );
@@ -171,6 +177,11 @@ export async function createRemoteCompaction(
     summary: `${REMOTE_SUMMARY_MARKER}\n\n${fallback}`,
     firstKeptEntryId: event.preparation.firstKeptEntryId,
     tokensBefore: event.preparation.tokensBefore,
+    ...(result.usage ? { usage: toPiUsage(
+      result.usage,
+      ctx.model!,
+      result.serviceTier && result.serviceTier !== "default" ? result.serviceTier : requestBody.service_tier,
+    ) } : {}),
     details: {
       kind: REMOTE_COMPACTION_KIND,
       version: 2,
@@ -247,7 +258,7 @@ async function captureCodexPayload(
   messages: ReturnType<typeof convertToLlm>,
   tools: readonly ToolInfoLike[],
   apiKey: string,
-  authHeaders: Record<string, string> | undefined,
+  authHeaders: Record<string, string | null> | undefined,
   sessionId: string,
   signal: AbortSignal,
   thinkingLevel: string | undefined,
@@ -534,7 +545,27 @@ function limitText(text: string, maxChars: number): string {
   return `${text.slice(0, head)}${omission}${text.slice(text.length - (available - head))}`;
 }
 
-type ToolInfoLike = Pick<Tool, "name" | "description" | "parameters">;
+type ToolInfoLike = Tool;
+
+function toPiUsage(raw: CodexCompactionUsage, model: Model<any>, tier: unknown): Usage {
+  const cacheRead = raw.cachedInputTokens ?? 0;
+  const cacheWrite = raw.cacheWriteInputTokens ?? 0;
+  const output = raw.outputTokens ?? 0;
+  const usage: Usage = {
+    input: Math.max(0, (raw.inputTokens ?? 0) - cacheRead - cacheWrite),
+    output,
+    cacheRead,
+    cacheWrite,
+    ...(raw.reasoningTokens !== undefined ? { reasoning: raw.reasoningTokens } : {}),
+    totalTokens: raw.totalTokens ?? (raw.inputTokens ?? 0) + output,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+  calculateCost(model, usage);
+  // Match Pi 0.85.1's catalog estimates, not subscription credit accounting.
+  const multiplier = tier === "priority" ? (model.id === "gpt-5.5" ? 2.5 : 2) : tier === "flex" ? 0.5 : 1;
+  for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) usage.cost[key] *= multiplier;
+  return usage;
+}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);