pi-codex-compaction 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-02
+
+### Added
+
+- Initial `pi-codex-compaction` extension.
+- OpenAI Codex RemoteCompactionV2 support with standard Pi compaction fallback.
+- Opaque checkpoint persistence and bounded cross-model fallback context.
+
+### Fixed
+
+- Use Pi's compat provider entry point so the extension loads through the runtime extension loader.
+- Rehydrate summaries emitted as untyped Responses message items after model switches.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best for the community, rather than us as individuals
+
+Examples of unacceptable behavior by participants include:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at jose@mocito.dev. All complaints will be reviewed and investigated promptly and fairly.
+
+Community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-codex-compaction`.
+
+## Development setup
+
+```bash
+npm install
+npm run -w packages/pi-codex-compaction check
+```
+
+This package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use.
+
+## Pull request checklist
+
+Before opening a pull request:
+
+- Run `npm run -w packages/pi-codex-compaction check`.
+- Run `npm test -w packages/pi-codex-compaction`.
+- Run `npm audit --omit=dev`.
+- Run `npm run -w packages/pi-codex-compaction pack:dry-run` and confirm the package contents are intentional.
+- Update `README.md` if user-visible behavior changes.
+- Update `CHANGELOG.md` for notable changes.
+- Keep examples and paths generic; do not commit API keys, tokens, auth headers, local settings, or provider configuration containing secrets.
+
+## Coding guidelines
+
+- Keep the Codex provider/API capability check explicit and future-compatible.
+- 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.
+
+## Code of conduct
+
+This project follows the Contributor Covenant Code of Conduct.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Mocito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# pi-codex-compaction
+
+Keep long Pi sessions usable on OpenAI Codex models by replacing Pi's local summary request with Codex's provider-side **RemoteCompactionV2** checkpoint when the current model supports the Codex Responses API.
+
+## Features
+
+- Uses the current `openai-codex` model for each compaction; it never silently changes the session model.
+- Sends only the history Pi is discarding, plus the previous Codex checkpoint, so the incoming/kept user message is not duplicated.
+- Persists Codex's opaque encrypted checkpoint and rehydrates it only for supported Codex requests.
+- Caps compaction input and response size and falls back to standard Pi compaction on failure.
+- 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.
+
+## Installation
+
+```bash
+pi install npm:pi-codex-compaction
+```
+
+For local development:
+
+```bash
+pi install /path/to/pi-mono/packages/pi-codex-compaction
+```
+
+Or load it for one run:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-codex-compaction
+```
+
+## Behavior
+
+When Pi starts compaction on a supported Codex model, the extension sends a streamed Responses request containing a `compaction_trigger` item and the `remote_compaction_v2` beta feature. The returned opaque checkpoint is stored in the Pi compaction entry. Later supported Codex requests replace the textual compaction marker with the raw checkpoint; 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. If it 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. No configuration is required.
+
+## Development
+
+```bash
+npm install
+npm run -w packages/pi-codex-compaction check
+npm test -w packages/pi-codex-compaction
+npm run -w packages/pi-codex-compaction pack:dry-run
+```

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of `pi-codex-compaction`.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected security vulnerabilities.
+
+Report privately through [GitHub Security Advisories](https://github.com/jvm/pi-mono/security/advisories/new) or by contacting the repository maintainer through GitHub. Include:
+
+- a description of the issue;
+- steps to reproduce;
+- affected versions or commits, if known;
+- any suggested mitigation.
+
+## Security model
+
+`pi-codex-compaction` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
+
+For supported `openai-codex` models, the extension sends the portion of conversation Pi is about to discard to the OpenAI Codex Responses endpoint over HTTPS, using credentials and provider headers resolved by Pi. It stores the provider-issued opaque `encrypted_content` checkpoint in the local Pi session's compaction details so supported Codex requests can reuse it. The checkpoint is not decoded, printed, or logged.
+
+The extension bounds compaction input and response size, validates the Codex HTTPS endpoint and account claim, honors Pi cancellation, and falls back to standard Pi compaction on authentication, transport, response, or context-limit failures. A bounded textual transcript excerpt remains in the compaction summary so switching to another model or provider does not leave the session with only an unusable Codex checkpoint. The fallback may contain conversation content already present in the local session and is still subject to the user's normal Pi session-file permissions.
+
+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.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development and validation instructions.

package/extensions/index.ts

@@ -0,0 +1,52 @@
+import type {
+  ExtensionAPI,
+  ExtensionHandler,
+  SessionBeforeCompactEvent,
+} from "@earendil-works/pi-coding-agent";
+import { BETA_FEATURE } from "../src/codex-wire.js";
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
+import {
+  applyRemoteCompactionMarker,
+  createRemoteCompaction,
+  findActiveRemoteCompaction,
+  supportsRemoteCompaction,
+} from "../src/remote-compaction.js";
+
+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;
+
+    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 }));
+      });
+      return compaction ? { compaction } : undefined;
+    } catch {
+      if (!event.signal.aborted && ctx.hasUI) {
+        ctx.ui.notify("Codex remote compaction failed; using standard Pi compaction.", "warning");
+      }
+      return undefined;
+    }
+  };
+  pi.on("session_before_compact", onBeforeCompact);
+
+  pi.on("before_provider_headers", (event, ctx) => {
+    if (!supportsRemoteCompaction(ctx.model)) return;
+    const existing = event.headers["x-codex-beta-features"];
+    const features = existing?.split(",").map((feature) => feature.trim()).filter(Boolean) ?? [];
+    if (!features.includes(BETA_FEATURE)) features.push(BETA_FEATURE);
+    event.headers["x-codex-beta-features"] = features.join(",");
+  });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    if (!supportsRemoteCompaction(ctx.model)) return;
+    const details = findActiveRemoteCompaction(ctx.sessionManager.buildContextEntries());
+    if (!details) return;
+    return applyRemoteCompactionMarker(event.payload, details);
+  });
+}

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./extensions/index.js";

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pi-codex-compaction",
+  "version": "0.1.0",
+  "description": "Use OpenAI Codex RemoteCompactionV2 for supported Pi sessions.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jose Mocito",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvm/pi-mono.git",
+    "directory": "packages/pi-codex-compaction"
+  },
+  "bugs": {
+    "url": "https://github.com/jvm/pi-mono/issues"
+  },
+  "homepage": "https://github.com/jvm/pi-mono/tree/main/packages/pi-codex-compaction#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "compaction",
+    "openai-codex",
+    "remote-compaction"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mjs",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
+  }
+}

package/src/codex-wire.ts

@@ -0,0 +1,211 @@
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const MAX_ENCRYPTED_CONTENT_CHARS = 2_000_000;
+const REQUEST_TIMEOUT_MS = 120_000;
+const ACCOUNT_ID_CLAIM = "https://api.openai.com/auth";
+export const BETA_FEATURE = "remote_compaction_v2";
+
+export interface CodexCompactionRequest {
+  model: {
+    id: string;
+    baseUrl: string;
+    headers?: Record<string, string>;
+  };
+  apiKey: string;
+  authHeaders?: Record<string, string>;
+  sessionId?: string;
+  body: Record<string, unknown>;
+  signal?: AbortSignal;
+}
+
+export async function requestRemoteCompaction(request: CodexCompactionRequest): Promise<string> {
+  const accountId = extractAccountId(request.apiKey);
+  const headers = buildHeaders(request, accountId);
+  const { signal, cleanup } = requestSignal(request.signal);
+
+  try {
+    const response = await fetch(resolveCodexResponsesUrl(request.model.baseUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(request.body),
+      signal,
+    });
+
+    if (!response.ok) {
+      if (response.body) await response.body.cancel().catch(() => undefined);
+      throw new Error(`Codex compaction request returned HTTP ${response.status}`);
+    }
+
+    return parseCompactionSse(await readBoundedBody(response));
+  } finally {
+    cleanup();
+  }
+}
+
+export function resolveCodexResponsesUrl(baseUrl: string): string {
+  const url = new URL(baseUrl);
+  if (url.protocol !== "https:") {
+    throw new Error("Codex compaction requires an HTTPS endpoint");
+  }
+  if (url.username || url.password) {
+    throw new Error("Codex compaction endpoint must not contain URL credentials");
+  }
+
+  const path = url.pathname.replace(/\/+$/, "");
+  if (path.endsWith("/codex/responses")) {
+    return url.toString();
+  }
+  url.pathname = path.endsWith("/codex") ? `${path}/responses` : `${path}/codex/responses`;
+  return url.toString();
+}
+
+export function parseCompactionSse(sse: string): string {
+  const encryptedContents = new Set<string>();
+  let completed = false;
+
+  for (const frame of sse.split(/\r?\n\r?\n/)) {
+    const data = frame
+      .split(/\r?\n/)
+      .filter((line) => line.startsWith("data:"))
+      .map((line) => line.slice(5).trim())
+      .join("\n")
+      .trim();
+    if (!data || data === "[DONE]") continue;
+
+    let event: unknown;
+    try {
+      event = JSON.parse(data) as unknown;
+    } catch {
+      throw new Error("Codex compaction returned invalid SSE data");
+    }
+    if (!isRecord(event)) continue;
+
+    if (event.type === "error" || event.type === "response.failed") {
+      throw new Error("Codex compaction response failed");
+    }
+
+    if (event.type === "response.output_item.done") {
+      collectCompactionItem(event.item, encryptedContents);
+    }
+
+    if (event.type === "response.completed" || event.type === "response.done") {
+      const response = isRecord(event.response) ? event.response : undefined;
+      collectOutputItems(response?.output, encryptedContents);
+      completed = response?.status === undefined || response.status === "completed";
+    }
+  }
+
+  if (!completed) {
+    throw new Error("Codex compaction stream ended before response completion");
+  }
+  if (encryptedContents.size !== 1) {
+    throw new Error(`Codex compaction returned ${encryptedContents.size} checkpoint items`);
+  }
+  return [...encryptedContents][0];
+}
+
+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);
+
+  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);
+  headers.set("accept", "text/event-stream");
+  headers.set("content-type", "application/json");
+
+  const sessionId = safeSessionId(request.sessionId);
+  if (sessionId) {
+    headers.set("session-id", sessionId);
+    headers.set("x-client-request-id", sessionId);
+  }
+  return headers;
+}
+
+function extractAccountId(token: string): string {
+  const segment = token.split(".")[1];
+  if (!segment) throw new Error("Codex authentication token has no account claim");
+
+  try {
+    const payload = JSON.parse(Buffer.from(segment, "base64url").toString("utf8")) as unknown;
+    const claim = isRecord(payload) ? payload[ACCOUNT_ID_CLAIM] : undefined;
+    const accountId = isRecord(claim) ? claim.chatgpt_account_id : undefined;
+    if (typeof accountId !== "string" || !/^[A-Za-z0-9._-]{1,256}$/.test(accountId)) {
+      throw new Error("missing account claim");
+    }
+    return accountId;
+  } catch {
+    throw new Error("Codex authentication token has no valid account claim");
+  }
+}
+
+function safeSessionId(value: string | undefined): string | undefined {
+  if (!value || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) return undefined;
+  return value;
+}
+
+function collectOutputItems(value: unknown, encryptedContents: Set<string>): void {
+  if (!Array.isArray(value)) return;
+  for (const item of value) collectCompactionItem(item, encryptedContents);
+}
+
+function collectCompactionItem(value: unknown, encryptedContents: Set<string>): void {
+  if (!isRecord(value) || value.type !== "compaction") return;
+  const encryptedContent = value.encrypted_content;
+  if (
+    typeof encryptedContent === "string" &&
+    encryptedContent.length > 0 &&
+    encryptedContent.length <= MAX_ENCRYPTED_CONTENT_CHARS
+  ) {
+    encryptedContents.add(encryptedContent);
+  }
+}
+
+async function readBoundedBody(response: Response): Promise<string> {
+  if (!response.body) throw new Error("Codex compaction response has no body");
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        throw new Error("Codex compaction response exceeded the size limit");
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    return text + decoder.decode();
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+function requestSignal(signal: AbortSignal | undefined): { signal: AbortSignal; cleanup: () => void } {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) {
+    controller.abort(signal.reason);
+  } else {
+    signal?.addEventListener("abort", onAbort, { once: true });
+  }
+  const timeout = setTimeout(() => controller.abort(new Error("Codex compaction request timed out")), REQUEST_TIMEOUT_MS);
+
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export const PACKAGE_NAME = "pi-codex-compaction";
+
+export * from "./codex-wire.js";
+export * from "./remote-compaction.js";

package/src/install-telemetry.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-codex-compaction";
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
+const CI_ENVIRONMENT_VARIABLES = [
+  "APPVEYOR",
+  "BITBUCKET_BUILD_NUMBER",
+  "BUILDKITE",
+  "CIRCLECI",
+  "CODESPACES",
+  "DRONE",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "JENKINS_URL",
+  "NETLIFY",
+  "TEAMCITY_VERSION",
+  "TF_BUILD",
+  "TRAVIS",
+  "VERCEL",
+];
+
+interface PiSettingsDocument {
+  enableInstallTelemetry?: unknown;
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isPresentEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isTruthyEnvFlag(process.env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]))) return false;
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  const packageJson = readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url))) as { version?: unknown };
+  return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+}
+
+export function reportInstallTelemetry(): void {
+  try {
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-codex-compaction-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
+  } catch {
+    // Best-effort telemetry: ignore local policy and filesystem failures.
+  }
+}

package/src/remote-compaction.ts

@@ -0,0 +1,388 @@
+import { stream as captureProviderPayload } from "@earendil-works/pi-ai/compat";
+import type { Model, Tool } 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";
+import { requestRemoteCompaction } from "./codex-wire.js";
+
+export const REMOTE_SUMMARY_MARKER = "[pi-codex-compaction:v1]";
+export const REMOTE_COMPACTION_KIND = "pi-codex-compaction";
+
+const FALLBACK_SUMMARY_MAX_CHARS = 12_000;
+const MAX_ENCRYPTED_CONTENT_CHARS = 2_000_000;
+const COMPACTION_RESPONSE_RESERVE_TOKENS = 8_192;
+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:";
+
+export interface RemoteCompactionDetails {
+  kind: typeof REMOTE_COMPACTION_KIND;
+  version: 1;
+  provider: "openai-codex";
+  model: string;
+  encryptedContent: string;
+}
+
+type CodexModel = Pick<Model<any>, "id" | "api" | "provider" | "baseUrl" | "contextWindow" | "headers">;
+type AgentMessage = ReturnType<typeof sessionEntryToContextMessages>[number];
+
+export function supportsRemoteCompaction(model: Pick<CodexModel, "api" | "provider"> | undefined): boolean {
+  return model?.provider === "openai-codex" && model.api === "openai-codex-responses";
+}
+
+export function findActiveRemoteCompaction(entries: readonly SessionEntry[]): RemoteCompactionDetails | undefined {
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const entry = entries[index];
+    if (entry.type !== "compaction") continue;
+    return isRemoteCompactionDetails(entry.details) ? entry.details : undefined;
+  }
+  return undefined;
+}
+
+export function applyRemoteCompactionMarker(payload: unknown, details: RemoteCompactionDetails): unknown | undefined {
+  if (!isRecord(payload) || !Array.isArray(payload.input)) return undefined;
+
+  let replaced = false;
+  const input = payload.input.map((item) => {
+    if (replaced || !isCompactionSummaryInput(item)) return item;
+    replaced = true;
+    return {
+      type: "compaction",
+      encrypted_content: details.encryptedContent,
+    };
+  });
+  return replaced ? { ...payload, input } : undefined;
+}
+
+export async function createRemoteCompaction(
+  event: SessionBeforeCompactEvent,
+  ctx: ExtensionContext,
+  getTools: () => readonly ToolInfoLike[],
+): Promise<{
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  details: RemoteCompactionDetails;
+} | undefined> {
+  const model = ctx.model as CodexModel | undefined;
+  if (!model || !supportsRemoteCompaction(model)) return undefined;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model as Model<any>);
+  if (!auth.ok || !auth.apiKey) return undefined;
+
+  const previous = findActiveRemoteCompaction(ctx.sessionManager.buildContextEntries());
+  const messages = [...event.preparation.messagesToSummarize, ...event.preparation.turnPrefixMessages];
+  const instructions = ctx.getSystemPrompt() || "You are a helpful assistant.";
+  const sessionId = ctx.sessionManager.getSessionId();
+  const providerPayload = await captureCodexPayload(
+    model,
+    instructions,
+    convertToLlm(messages),
+    getTools(),
+    auth.apiKey,
+    sessionId,
+    event.signal,
+  );
+  if (!providerPayload) return undefined;
+  const providerInput = providerPayload.input;
+  if (!Array.isArray(providerInput)) return undefined;
+  const providerTools = Array.isArray(providerPayload.tools) ? providerPayload.tools : [];
+
+  const input = appendCompactionItems(providerInput, event.preparation, previous);
+  const boundedInput = boundCompactionInput(input, instructions, providerTools, model.contextWindow);
+  if (!boundedInput) return undefined;
+
+  const encryptedContent = await requestRemoteCompaction({
+    model,
+    apiKey: auth.apiKey,
+    authHeaders: auth.headers,
+    sessionId,
+    body: {
+      ...providerPayload,
+      model: model.id,
+      store: false,
+      stream: true,
+      input: boundedInput,
+    },
+    signal: event.signal,
+  });
+
+  const fallback = buildFallbackSummary(event.preparation, messages);
+  return {
+    summary: `${REMOTE_SUMMARY_MARKER}\n\n${fallback}`,
+    firstKeptEntryId: event.preparation.firstKeptEntryId,
+    tokensBefore: event.preparation.tokensBefore,
+    details: {
+      kind: REMOTE_COMPACTION_KIND,
+      version: 1,
+      provider: "openai-codex",
+      model: model.id,
+      encryptedContent,
+    },
+  };
+}
+
+export function buildCompactionInput(
+  model: CodexModel,
+  preparation: SessionBeforeCompactEvent["preparation"],
+  messages: AgentMessage[],
+  previous: RemoteCompactionDetails | undefined,
+): unknown[] {
+  return appendCompactionItems(convertCompactionMessages(model, convertToLlm(messages)), preparation, previous);
+}
+
+export function boundCompactionInput(
+  input: readonly unknown[],
+  instructions: string,
+  tools: readonly unknown[],
+  contextWindow: number,
+): unknown[] | undefined {
+  const budget = Math.max(1, contextWindow - COMPACTION_RESPONSE_RESERVE_TOKENS);
+  const bounded = input.map((item) => item);
+  let estimatedTokens = estimateConservativeTokens({ instructions, input: bounded, tools });
+  const fits = () => estimatedTokens <= budget;
+  if (fits()) return bounded;
+
+  // 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.
+  for (let index = bounded.length - 1; index >= 0; index--) {
+    const item = bounded[index];
+    if (!isRecord(item)) continue;
+
+    const replacement = item.type === "function_call_output"
+      ? { ...item, output: TRUNCATED_TOOL_OUTPUT }
+      : item.type === "tool_search_output"
+        ? { ...item, tools: [] }
+        : undefined;
+    if (!replacement) continue;
+
+    estimatedTokens += estimateConservativeTokens(replacement) - estimateConservativeTokens(item);
+    bounded[index] = replacement;
+    if (fits()) return bounded;
+  }
+
+  return undefined;
+}
+
+export function buildFallbackSummary(preparation: SessionBeforeCompactEvent["preparation"], messages: AgentMessage[]): string {
+  const transcript = serializeConversation(convertToLlm(messages));
+  const previous = preparation.previousSummary ? `Previous checkpoint fallback:\n${preparation.previousSummary}` : "";
+  const content = [
+    "This checkpoint is opaque to non-Codex providers. Use the transcript excerpt below when continuing this session.",
+    previous,
+    transcript ? `Discarded conversation excerpt:\n${transcript}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+  return `<codex-compaction-fallback>\n${limitText(content, FALLBACK_SUMMARY_MAX_CHARS)}\n</codex-compaction-fallback>`;
+}
+
+async function captureCodexPayload(
+  model: CodexModel,
+  instructions: string,
+  messages: ReturnType<typeof convertToLlm>,
+  tools: readonly ToolInfoLike[],
+  apiKey: string,
+  sessionId: string,
+  signal: AbortSignal,
+): Promise<Record<string, unknown> | undefined> {
+  if (signal.aborted) return undefined;
+
+  let payload: unknown;
+  const captureError = new Error("capture Codex request payload");
+  const stream = captureProviderPayload(model as Model<any>, {
+    systemPrompt: instructions,
+    messages,
+    tools: [...tools],
+  }, {
+    apiKey,
+    sessionId,
+    signal,
+    onPayload(next) {
+      payload = next;
+      throw captureError;
+    },
+  });
+
+  await stream.result();
+  return isRecord(payload) ? payload : undefined;
+}
+
+function appendCompactionItems(
+  input: readonly unknown[],
+  preparation: SessionBeforeCompactEvent["preparation"],
+  previous: RemoteCompactionDetails | undefined,
+): unknown[] {
+  const output = [...input];
+  if (previous) {
+    output.unshift({ type: "compaction", encrypted_content: previous.encryptedContent });
+  } else if (preparation.previousSummary) {
+    output.unshift({
+      type: "message",
+      role: "user",
+      content: [{ type: "input_text", text: limitText(preparation.previousSummary, FALLBACK_SUMMARY_MAX_CHARS) }],
+      status: "completed",
+    });
+  }
+  output.push({ type: "compaction_trigger" });
+  return output;
+}
+
+function convertCompactionMessages(model: CodexModel, messages: readonly unknown[]): unknown[] {
+  const input: unknown[] = [];
+  let messageIndex = 0;
+
+  for (const rawMessage of messages) {
+    if (!isRecord(rawMessage)) continue;
+    const role = rawMessage.role;
+
+    if (role === "user") {
+      const content = convertUserContent(rawMessage.content);
+      if (content.length > 0) input.push({ type: "message", role: "user", content });
+    } else if (role === "assistant") {
+      const output: unknown[] = [];
+      const sourceIsSameResponsesApi = rawMessage.provider === model.provider && rawMessage.api === model.api;
+      const differentModel = sourceIsSameResponsesApi && rawMessage.model !== model.id;
+      let textIndex = 0;
+      if (Array.isArray(rawMessage.content)) {
+        for (const rawBlock of rawMessage.content) {
+          if (!isRecord(rawBlock)) continue;
+          if (rawBlock.type === "thinking" && typeof rawBlock.thinkingSignature === "string") {
+            try {
+              const reasoning = JSON.parse(rawBlock.thinkingSignature) as unknown;
+              if (isRecord(reasoning)) output.push(reasoning);
+            } catch {
+              // Ignore malformed reasoning signatures; the textual/tool history remains usable.
+            }
+          } else if (rawBlock.type === "text" && typeof rawBlock.text === "string") {
+            const signature = parseTextSignature(rawBlock.textSignature);
+            output.push({
+              type: "message",
+              role: "assistant",
+              content: [{ type: "output_text", text: rawBlock.text, annotations: [] }],
+              status: "completed",
+              id: signature?.id ?? `msg_pi_${messageIndex}${textIndex ? `_${textIndex}` : ""}`,
+              ...(signature?.phase ? { phase: signature.phase } : {}),
+            });
+            textIndex++;
+          } else if (rawBlock.type === "toolCall" && typeof rawBlock.id === "string") {
+            const [callId, itemIdRaw] = splitToolCallId(rawBlock.id);
+            output.push({
+              type: "function_call",
+              ...(itemIdRaw && !differentModel ? { id: normalizeResponseItemId(itemIdRaw) } : {}),
+              call_id: callId,
+              name: typeof rawBlock.name === "string" ? rawBlock.name : "",
+              arguments: JSON.stringify(rawBlock.arguments ?? {}),
+            });
+          }
+        }
+      }
+      input.push(...output);
+    } else if (role === "toolResult") {
+      const content = Array.isArray(rawMessage.content) ? rawMessage.content : [];
+      const text = content
+        .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
+        .map((part) => part.text as string)
+        .join("\n");
+      const hasImage = content.some((part) => isRecord(part) && part.type === "image");
+      const toolCallId = typeof rawMessage.toolCallId === "string" ? rawMessage.toolCallId : "";
+      input.push({
+        type: "function_call_output",
+        call_id: splitToolCallId(toolCallId)[0],
+        output: text || (hasImage ? "(see attached image)" : "(no tool output)"),
+      });
+    }
+
+    messageIndex++;
+  }
+
+  return input;
+}
+
+function convertUserContent(value: unknown): unknown[] {
+  if (typeof value === "string") return [{ type: "input_text", text: value }];
+  if (!Array.isArray(value)) return [];
+
+  const content: unknown[] = [];
+  for (const part of value) {
+    if (!isRecord(part)) continue;
+    if (part.type === "text" && typeof part.text === "string") {
+      content.push({ type: "input_text", text: part.text });
+    } else if (part.type === "image" && typeof part.mimeType === "string" && typeof part.data === "string") {
+      content.push({ type: "input_image", detail: "auto", image_url: `data:${part.mimeType};base64,${part.data}` });
+    }
+  }
+  return content;
+}
+
+function parseTextSignature(value: unknown): { id: string; phase?: string } | undefined {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  if (!value.startsWith("{")) return { id: value.slice(0, 64) };
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!isRecord(parsed) || typeof parsed.id !== "string") return undefined;
+    return {
+      id: parsed.id.slice(0, 64),
+      ...(typeof parsed.phase === "string" ? { phase: parsed.phase } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function splitToolCallId(value: string): [string, string | undefined] {
+  const separator = value.indexOf("|");
+  return separator < 0 ? [value, undefined] : [value.slice(0, separator), value.slice(separator + 1)];
+}
+
+function normalizeResponseItemId(value: string): string {
+  let normalized = value.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64).replace(/_+$/, "");
+  if (!normalized.startsWith("fc")) normalized = `fc_${normalized}`;
+  return normalized.slice(0, 64);
+}
+
+function isCompactionSummaryInput(value: unknown): boolean {
+  if (!isRecord(value) || (value.type !== undefined && value.type !== "message") || value.role !== "user" || !Array.isArray(value.content)) {
+    return false;
+  }
+  return value.content.some(
+    (part) =>
+      isRecord(part) &&
+      part.type === "input_text" &&
+      typeof part.text === "string" &&
+      part.text.trimStart().startsWith(PI_COMPACTION_SUMMARY_PREFIX) &&
+      part.text.includes(REMOTE_SUMMARY_MARKER),
+  );
+}
+
+function isRemoteCompactionDetails(value: unknown): value is RemoteCompactionDetails {
+  return (
+    isRecord(value) &&
+    value.kind === REMOTE_COMPACTION_KIND &&
+    value.version === 1 &&
+    value.provider === "openai-codex" &&
+    typeof value.model === "string" &&
+    value.model.length > 0 &&
+    typeof value.encryptedContent === "string" &&
+    value.encryptedContent.length > 0 &&
+    value.encryptedContent.length <= MAX_ENCRYPTED_CONTENT_CHARS
+  );
+}
+
+function estimateConservativeTokens(value: unknown): number {
+  // One UTF-8 byte per token is deliberately conservative without a provider tokenizer.
+  return new TextEncoder().encode(JSON.stringify(value) ?? "").byteLength;
+}
+
+function limitText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const omission = "\n\n[… earlier fallback context omitted …]\n\n";
+  const available = Math.max(0, maxChars - omission.length);
+  const head = Math.floor(available * 0.35);
+  return `${text.slice(0, head)}${omission}${text.slice(text.length - (available - head))}`;
+}
+
+type ToolInfoLike = Pick<Tool, "name" | "description" | "parameters">;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}