@criogaid/pi-codex-compaction 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# pi-codex-compaction
+
+## 未发布
+
+## 0.3.0
+
+- npm 发布包名改为 `@criogaid/pi-codex-compaction`。新增标签触发的发布流程，通过版本核对、类型检查、测试和打包检查后发布，并提供源码来源证明；现有配置路径和会话格式保持不变。
+- 要求 Pi 0.99.1 或更新版本。远程压缩沿用当前会话的思考等级、session ID、缓存与重试配置，并保留 Provider 认证环境及请求头覆盖。
+- 复用普通请求的投影上下文和有效系统提示词；会话、模型、后端或历史前缀改变时停止复用。同一后端内切换模型仍可重放检查点。
+- 按 Codex 默认规则筛选保留历史并估算 UTF-8 文本和图片预算，在发送前缩减超出可用上下文的末尾工具输出。
+- 新增 `/codex-compaction` 菜单、V2 总开关及降级模型配置。开关明确保存布尔值，关闭时保留所选模型；V2 关闭或失败时按配置使用 Pi 原生摘要。配置在每次压缩开始时固定，已启用的降级模型失败则取消压缩。
+- 将文本摘要设置命名为 `Use separate summary model` 和 `Summary model and thinking level`。使用 Pi 原生设置说明区域解释它们与 V2 的关系，RPC 显示相同的文本压缩条件。配置字段与压缩行为保持不变。
+- 改写 README 和 V2 开关说明，用聊天记录、文字摘要和模型服务解释压缩行为与限制。
+- 无效 fallback 配置仍允许打开菜单、切换 V2 或选择新模型。切换 V2 原样保留无效配置，合法配置写回规范格式；校验错误包含文件路径。
+- V2 固定使用 SSE，确保压缩功能头不受已有 WebSocket 连接影响。普通对话和文本降级仍使用 Pi 的传输设置。
+- 虚拟降级模型的展示限额不再提前缩减摘要预算，由 Pi 路由后的实际模型限制输出。
+- 新检查点按 UTF-16 码元顺序排列对象键，避免指纹依赖系统语言。旧指纹只有在创建时分支上通过精确验证后才在内存中转换；checkpoint version 1 和消息编辑保护保持兼容。
+- 当前模型不支持 V2 时，普通请求跳过消息指纹和上下文快照计算。
+- 源码迁至 `src/`，测试迁至 `tests/`，通过 npm 锁文件安装依赖。删除独立迁移记录、设计归档和 Changesets 流程，打包及 Pi 入口加载检查归入测试。
+
+## 0.2.2
+
+### Patch Changes
+
+- f8a5343: 精简并重写面向用户的安装、使用、配置和限制说明。
+
+## 0.2.1
+
+### Patch Changes
+
+- 74df898: Update package repository metadata after renaming the monorepo to pi-extensions.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9b9fc40: 新增 Provider-aware 的 Codex Remote Compaction V2，支持严格的 endpoint、协议和 checkpoint 身份校验，并在失败时安全回退到 Pi 原生压缩。

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Narumi
+Copyright (c) 2026 Anthony
+
+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,172 @@
+# pi-codex-compaction
+
+为 [Pi](https://github.com/earendil-works/pi) 提供 Codex Remote Compaction V2，让支持它的服务压缩聊天记录。你也可以指定一个独立模型生成文字摘要，用一个模型聊天，用另一个模型压缩。
+
+手动执行 `/compact`、Pi 自动压缩，以及聊天记录超出模型容量后触发的压缩，都使用这套设置。压缩不会改变当前对话模型或思考等级。
+
+## 安装
+
+需要 Pi 0.99.1 或更新版本：
+
+```bash
+pi install npm:@criogaid/pi-codex-compaction
+```
+
+也可以从 Git 仓库安装：
+
+```bash
+pi install git:github.com/Criogaid/pi-codex-compaction
+```
+
+不要安装不带作用域的 `pi-codex-compaction`，它属于另一个仓库。
+
+## 开始使用
+
+如果你使用 Pi 自带的 `openai-codex` 服务商配置和官方地址，安装后即可执行 `/compact`。扩展默认先尝试 V2；V2 失败时，交给 Pi 使用当前模型生成文字摘要。
+
+要用指定模型生成文字摘要，执行：
+
+```text
+/codex-compaction
+```
+
+菜单按以下顺序显示：
+
+| 设置 | 用途 |
+| --- | --- |
+| Remote Compaction V2 | 是否优先尝试远程压缩，默认 On |
+| Use separate summary model | 是否使用独立模型生成文字摘要，默认 Off |
+| Summary model and thinking level | 选择摘要模型及其思考等级 |
+
+首次选择模型后，还需要打开 `Use separate summary model`。如果想始终使用指定模型生成文字摘要，同时关闭 `Remote Compaction V2`。
+
+在终端菜单中选中一项，列表下方会显示它的用途及其与其他设置的关系。通过 RPC 使用 Pi 的客户端会在选择框标题中看到何时使用文字摘要，以及当前选用了哪个模型。
+
+终端菜单中按回车或空格切换开关，修改立即保存，菜单停留在原来的行。模型可以按服务商（Provider）、ID 或名称搜索。关闭 `Use separate summary model` 会保留已选模型；取消模型选择不会保存。RPC 模式每次操作后退出菜单。
+
+例如，你希望保留当前对话模型，但用另一个模型压缩：在第三项选好模型和思考等级，将前两项分别设为 Off、On，再执行 `/compact`。扩展会显示实际使用的压缩模型，摘要完成后继续原来的对话。
+
+## 压缩规则
+
+| V2 设置与当前模型 | 下一步 |
+| --- | --- |
+| V2 开启，模型支持协议 | 用当前模型尝试 V2；失败后改用文字摘要压缩 |
+| V2 关闭，或模型不支持协议 | 直接用文字摘要压缩 |
+
+需要文字摘要时，只有打开 `Use separate summary model` 且选好了模型，才会使用该模型；否则由 Pi 使用当前对话模型。模型的登录凭据和思考等级沿用 Pi 的配置。如果选择的是虚拟模型，Pi 会按它的配置选择实际发送请求的模型。
+
+如果启用的独立摘要模型不可用或请求失败，本次压缩会停止，不再改用当前对话模型。摘要为空、生成被中断或因长度限制而截断时，也会停止压缩。
+
+在 `/compact` 后面附加的要求，例如“重点保留尚未完成的任务”，只对文字摘要生效。V2 不接受这些要求，扩展会提示它们被忽略。
+
+## 手动配置
+
+设置保存在：
+
+```text
+~/.pi/agent/extensions/pi-codex-compaction/config.json
+```
+
+如果设置了 `PI_CODING_AGENT_DIR`，则使用该目录下的 `extensions/pi-codex-compaction/config.json`。菜单会在保存时创建文件；非交互模式可以直接编辑它。
+
+下面的配置优先尝试 V2，需要文字摘要时使用指定模型：
+
+```json
+{
+  "version": 1,
+  "remoteCompaction": {
+    "enabled": true
+  },
+  "fallback": {
+    "enabled": true,
+    "provider": "your-provider",
+    "model": "your-model",
+    "thinkingLevel": "high"
+  }
+}
+```
+
+将 `provider`、`model` 替换为 Pi 中的实际 ID，`thinkingLevel` 使用该模型支持的值。这里不保存 API key，模型和认证需要先在 Pi 中配置好。
+
+配置中的 `fallback` 对应菜单里的独立摘要模型设置，`fallback.enabled` 对应 `Use separate summary model`。省略整个 `fallback` 表示未指定模型；旧配置如果省略了 `enabled`，按开启处理。模型的 `provider`、`model` 和 `thinkingLevel` 必须同时提供或同时省略。
+
+省略 `remoteCompaction` 默认开启 V2。配置文件须为 UTF-8 JSON，大小不超过 16 KiB。
+
+每次压缩开始时读取配置，压缩途中修改设置会在下次生效。文件无法读取、JSON 格式错误或 V2 设置无效时会停止压缩。独立摘要模型的配置只在需要文字摘要时检查，因此这部分填错不会影响成功的 V2 压缩。
+
+独立摘要模型的配置无效时，菜单显示 `Invalid`。你仍可切换 V2，已填写的模型配置会保留。重新选择模型可以修复这部分配置，但之后需要打开 `Use separate summary model` 才会使用它。如果打开菜单后配置文件被其他程序修改，保存会失败；重新打开菜单再操作即可。
+
+## 自定义网关
+
+网关必须支持 Codex Remote Compaction V2，只有普通 Responses API 兼容性还不够。模型的 API 类型须为 `openai-responses` 或 `openai-codex-responses`。
+
+在 Pi 的 `models.json` 中为模型添加 `compat.remoteCompaction`。以下是 `openai-responses` 配置示例：
+
+```json
+{
+  "providers": {
+    "custom-codex": {
+      "baseUrl": "https://gateway.example.com/v1",
+      "api": "openai-responses",
+      "apiKey": "$CUSTOM_CODEX_API_KEY",
+      "models": [
+        {
+          "id": "gpt-example",
+          "compat": {
+            "remoteCompaction": {
+              "protocol": "v2"
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+替换地址和模型 ID，并设置 `CUSTOM_CODEX_API_KEY` 环境变量。这个例子请求 `https://gateway.example.com/v1/responses`。
+
+如果网关的压缩请求使用其他路径，可以在 `remoteCompaction` 内增加 `endpoint`。它的协议、主机和端口必须与 Pi 登录认证后实际使用的 `baseUrl` 一致，URL 不能包含用户名、密码、`?` 后的查询参数或 `#` 后的片段。填写这些字段前，须确认网关本身支持 V2。
+
+## 使用前需要了解
+
+关闭 V2 后改用文字摘要压缩，不影响已压缩的聊天记录。
+
+V2 压缩后的旧聊天记录以加密数据保存，只有支持它的模型服务才能使用，扩展无法把它还原成完整文字。重新打开会话或从会话创建分支时，可以继续使用这部分记录，但必须连接原来的服务商，并保持 API 类型和请求地址不变。换到其他服务商或地址后，文字摘要只能根据 Pi 仍能读取的摘要和消息生成，无法包含那部分加密的旧记录。
+
+在同一服务和地址下切换模型，扩展也会继续发送已压缩的记录。如果新模型不接受这些数据，需要切回原模型。V2 协议仍属实验性质。
+
+压缩后，Pi 还会保留一部分近期消息。如果这些消息被修改，扩展可能无法确认它们与已压缩记录是否对应，从而停止使用那部分记录。搭配会改写聊天内容的扩展时，请把本包放在 Pi 的 `packages` 列表中靠前的位置。
+
+扩展会尽量让压缩请求与普通聊天请求使用相同的历史内容和系统提示词，便于模型服务复用缓存。但 Pi 和其他扩展仍可能改变最终发送的内容，因此不能保证缓存命中或费用下降。
+
+## 开发
+
+使用 Node 24 或更新版本。在克隆后的仓库根目录运行：
+
+```bash
+npm ci --ignore-scripts
+npm run typecheck
+npm test
+npm run pack:check
+```
+
+本地加载可以使用 `pi install .`。Pi 不会替本地包安装依赖，须先完成上面的安装步骤。
+
+运行代码在 `src/`，入口是 `src/index.ts`；测试在 `tests/`，编译结果写入 Git 忽略的 `dist/`。Pi 直接加载 TypeScript 源码。打包检查同时验证发布文件清单和 Pi 的实际入口加载。
+
+[CI](.github/workflows/ci.yml) 在 Ubuntu 24.04 和 Windows 上使用 Node 24 执行验证。变更记录见 [CHANGELOG.md](CHANGELOG.md)，维护规则见 [AGENTS.md](AGENTS.md)。
+
+## 发布
+
+[Publish](.github/workflows/publish.yml) 在推送 `v*` 标签时运行。标签必须与 `package.json` 的版本一致，例如版本 `0.3.0` 对应标签 `v0.3.0`。流程目前只发布正式版本，不接受带 `-beta`、`-rc` 等后缀的预发布版本。
+
+首次发布前，在本仓库的 **Settings → Secrets and variables → Actions** 中添加 `NPM_TOKEN`。按 [npm 文档](https://docs.npmjs.com/creating-and-viewing-access-tokens)创建 granular access token，授予 `@criogaid` 作用域的发布权限（Read and write / publish and stage），并启用 Bypass two-factor authentication。包创建后，可以将 token 权限缩小到该包。
+
+准备版本时，运行 `npm version <版本号> --no-git-tag-version` 同步更新 `package.json` 和 `package-lock.json`，将本次改动从 CHANGELOG 的“未发布”整理到对应版本下。运行上面的三项验证命令，通过后提交，再为该提交创建并推送 `v<版本号>` 标签。
+
+工作流会核对版本，重新安装依赖，执行类型检查、测试和打包检查，全部通过后才发布公开 npm 包，并附带可追溯到源码提交和工作流的来源证明（provenance）。普通分支推送不会发布；已经发布的 npm 版本不能覆盖，后续修改需要使用新版本号。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。本仓库从 `Criogaid/pi-extensions-anthony` 提取并独立维护，实现基于 `@narumitw/pi-codex-compact`，保留 Narumi 和 Anthony 的署名。

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@criogaid/pi-codex-compaction",
+  "version": "0.3.0",
+  "description": "Provider-aware Codex Remote Compaction V2 for Pi.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Criogaid/pi-codex-compaction.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Criogaid/pi-codex-compaction/issues"
+  },
+  "homepage": "https://github.com/Criogaid/pi-codex-compaction#readme",
+  "author": "Anthony",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "codex",
+    "compaction",
+    "remote-compaction"
+  ],
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "tsc --project tsconfig.json && node --test \"dist/tests/*.test.js\"",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "pack:check": "tsc --project tsconfig.json && node --test dist/tests/package.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.99.1",
+    "@earendil-works/pi-ai": ">=0.99.1",
+    "@earendil-works/pi-coding-agent": ">=0.99.1",
+    "@earendil-works/pi-tui": ">=0.99.1"
+  },
+  "dependencies": {
+    "saxes": "6.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.99.1",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
+    "@types/node": "26.1.1",
+    "typescript": "7.0.2"
+  },
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ]
+  }
+}

package/src/capability.ts

@@ -0,0 +1,95 @@
+// Own model eligibility and endpoint identity; authentication supplies the effective base URL.
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { hasApi } from "@earendil-works/pi-ai";
+import { isObject } from "./protocol.js";
+
+export const CODEX_API = "openai-codex-responses" as const;
+export const OPENAI_RESPONSES_API = "openai-responses" as const;
+export type RemoteCompactionApi = typeof CODEX_API | typeof OPENAI_RESPONSES_API;
+const OFFICIAL_PROVIDER = "openai-codex";
+const OFFICIAL_BASE_URL = "https://chatgpt.com/backend-api";
+
+export interface ProviderIdentity {
+  readonly provider: string;
+  readonly api: RemoteCompactionApi;
+  readonly modelId: string;
+  readonly baseUrl: string;
+  readonly endpoint: string;
+}
+export interface CapableModel {
+  readonly model: Model<RemoteCompactionApi>;
+  readonly identity: ProviderIdentity;
+}
+
+export function normalizeUrl(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error("URL must use HTTP or HTTPS");
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("URL must not contain credentials, a query, or a fragment");
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+  return url.toString().replace(/\/$/, "");
+}
+/** Mirror Pi 0.99's resolveCodexUrl and the OpenAI SDK's `/responses` route for a normalized base URL. */
+export function deriveEndpoint(baseUrl: string, api: RemoteCompactionApi): string {
+  if (api === OPENAI_RESPONSES_API) return `${baseUrl}/responses`;
+  if (baseUrl.endsWith("/codex/responses")) return baseUrl;
+  if (baseUrl.endsWith("/codex")) return `${baseUrl}/responses`;
+  return `${baseUrl}/codex/responses`;
+}
+
+function configuredEndpoint(model: Model<RemoteCompactionApi>, baseUrl: string): string | undefined {
+  // Pi preserves extension metadata but its built-in compatibility type does not declare it.
+  const compat: unknown = model.compat;
+  const value = isObject(compat) ? compat.remoteCompaction : undefined;
+  if (!isObject(value) || value.protocol !== "v2" ||
+      (value.endpoint !== undefined && typeof value.endpoint !== "string")) return undefined;
+  try {
+    const endpoint = typeof value.endpoint === "string"
+      ? normalizeUrl(value.endpoint) : deriveEndpoint(baseUrl, model.api);
+    return new URL(baseUrl).origin === new URL(endpoint).origin ? endpoint : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function capableModel(model: Model<Api> | undefined, effectiveBaseUrl?: string): CapableModel | undefined {
+  if (!model || (!hasApi(model, CODEX_API) && !hasApi(model, OPENAI_RESPONSES_API))) return undefined;
+  let configuredBaseUrl: string;
+  let baseUrl: string;
+  try {
+    configuredBaseUrl = normalizeUrl(model.baseUrl);
+    baseUrl = effectiveBaseUrl === undefined ? configuredBaseUrl : normalizeUrl(effectiveBaseUrl);
+  } catch {
+    return undefined;
+  }
+  const endpoint = model.provider === OFFICIAL_PROVIDER && hasApi(model, CODEX_API) && configuredBaseUrl === OFFICIAL_BASE_URL
+    ? deriveEndpoint(baseUrl, CODEX_API) : configuredEndpoint(model, baseUrl);
+  return endpoint ? {
+    model,
+    identity: { provider: model.provider, api: model.api, modelId: model.id, baseUrl, endpoint },
+  } : undefined;
+}
+
+/** Compare provider and API before authentication resolves the endpoint. */
+export function sameProvider(
+  left: Pick<ProviderIdentity, "provider" | "api">,
+  right: { readonly provider: string; readonly api: string },
+): boolean {
+  return left.provider === right.provider && left.api === right.api;
+}
+
+export function sameModel(
+  left: Pick<ProviderIdentity, "provider" | "api" | "modelId">,
+  right: Pick<Model<Api>, "provider" | "api" | "id">,
+): boolean {
+  return sameProvider(left, right) && left.modelId === right.id;
+}
+
+/**
+ * Codex keeps compaction items across model switches on one backend and narrows that only by
+ * the server's comp_hash, which Pi does not expose. Checkpoints therefore bind to the backend.
+ */
+export function sameBackend(left: ProviderIdentity, right: ProviderIdentity): boolean {
+  return sameProvider(left, right) && left.baseUrl === right.baseUrl && left.endpoint === right.endpoint;
+}

package/src/checkpoint.ts

@@ -0,0 +1,261 @@
+// Own the versioned checkpoint format, endpoint binding, and exact Pi session projection.
+// Normalize legacy fingerprints from their creation-time branch without rewriting session entries.
+import { createHash, randomUUID } from "node:crypto";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { getCurrentSystemMessage, type Message } from "@earendil-works/pi-ai";
+import {
+  buildSessionProjection,
+  sessionEntryToContextMessages,
+  type CompactionEntry,
+  type ProjectedSessionEntry,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { isObject, type JsonObject, REMOTE_COMPACTION_PROTOCOL, validateCompactionItem } from "./protocol.js";
+import {
+  CODEX_API,
+  OPENAI_RESPONSES_API,
+  normalizeUrl,
+  type ProviderIdentity,
+} from "./capability.js";
+
+export const CHECKPOINT_KIND = "pi-codex-compaction";
+export const CHECKPOINT_VERSION = 1;
+
+export interface CodexCheckpointDetails extends ProviderIdentity {
+  kind: typeof CHECKPOINT_KIND;
+  version: typeof CHECKPOINT_VERSION;
+  checkpointId: string;
+  protocol: typeof REMOTE_COMPACTION_PROTOCOL;
+  replacementHistory: JsonObject[];
+  keptMessageFingerprints: string[];
+  createdAt: string;
+}
+
+function orderedValue(value: unknown, compareKeys: (left: string, right: string) => number): unknown {
+  if (Array.isArray(value)) return value.map((item) => orderedValue(item, compareKeys));
+  if (!isObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => compareKeys(left, right))
+      .map(([key, child]) => [key, orderedValue(child, compareKeys)]),
+  );
+}
+
+function digestMessage(message: AgentMessage, compareKeys: (left: string, right: string) => number): string {
+  return createHash("sha256").update(JSON.stringify(orderedValue(message, compareKeys))).digest("hex");
+}
+
+// Session and context messages are replaced rather than mutated, so object identity keys both caches.
+const fingerprints = new WeakMap<AgentMessage, string>();
+const checkpoints = new WeakMap<SessionEntry, CodexCheckpointDetails | null>();
+
+export function fingerprintMessage(message: AgentMessage): string {
+  let fingerprint = fingerprints.get(message);
+  if (fingerprint === undefined) {
+    // Compare UTF-16 code units; persisted hashes must not depend on the process locale or ICU collation.
+    fingerprint = digestMessage(message, (left, right) => left < right ? -1 : left > right ? 1 : 0);
+    fingerprints.set(message, fingerprint);
+  }
+  return fingerprint;
+}
+
+export function checkpointMarker(checkpointId: string): string {
+  return [
+    `[PI_CODEX_REMOTE_CHECKPOINT:${checkpointId}]`,
+    "Opaque checkpoint injection failed. Do not infer missing history; tell the user to re-enable",
+    "@oipsanthony/pi-codex-compaction with the checkpoint's provider and model.",
+  ].join(" ");
+}
+
+export function fallbackSummary(checkpointId: string): string {
+  return [
+    `Codex Remote Compaction V2 checkpoint ${checkpointId} stores the older history opaquely.`,
+    "Full replay requires @oipsanthony/pi-codex-compaction and the original provider endpoint and model.",
+    "Without them, only Pi's retained recent messages remain available.",
+  ].join(" ");
+}
+
+function markerMessage(checkpointId: string, timestamp: number): AgentMessage {
+  return {
+    role: "user",
+    content: [{ type: "text", text: checkpointMarker(checkpointId) }],
+    timestamp,
+  };
+}
+
+export function parseCheckpointDetails(value: unknown): CodexCheckpointDetails | undefined {
+  if (!isObject(value)) return undefined;
+  if (
+    value.kind !== CHECKPOINT_KIND ||
+    value.version !== CHECKPOINT_VERSION ||
+    typeof value.checkpointId !== "string" ||
+    value.checkpointId.length < 8 ||
+    typeof value.provider !== "string" ||
+    !value.provider ||
+    (value.api !== CODEX_API && value.api !== OPENAI_RESPONSES_API) ||
+    typeof value.modelId !== "string" ||
+    !value.modelId ||
+    typeof value.baseUrl !== "string" ||
+    typeof value.endpoint !== "string" ||
+    value.protocol !== REMOTE_COMPACTION_PROTOCOL ||
+    !Array.isArray(value.replacementHistory) ||
+    !Array.isArray(value.keptMessageFingerprints) ||
+    typeof value.createdAt !== "string"
+  ) {
+    return undefined;
+  }
+  try {
+    if (
+      normalizeUrl(value.baseUrl) !== value.baseUrl ||
+      normalizeUrl(value.endpoint) !== value.endpoint ||
+      new URL(value.baseUrl).origin !== new URL(value.endpoint).origin
+    ) {
+      return undefined;
+    }
+  } catch {
+    return undefined;
+  }
+  if (
+    value.replacementHistory.length === 0 ||
+    !value.replacementHistory.every(isObject) ||
+    !value.keptMessageFingerprints.every(
+      (fingerprint) => typeof fingerprint === "string" && /^[a-f0-9]{64}$/.test(fingerprint),
+    )
+  ) {
+    return undefined;
+  }
+  try {
+    const item = validateCompactionItem(value.replacementHistory.at(-1));
+    const parsed = structuredClone(value) as unknown as CodexCheckpointDetails;
+    parsed.replacementHistory[parsed.replacementHistory.length - 1] = item;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function retainedEntries(
+  branchEntries: readonly SessionEntry[],
+  leafId: string | null,
+  firstKeptEntryId: string,
+): ProjectedSessionEntry[] | undefined {
+  const projection = buildSessionProjection([...branchEntries], leafId);
+  const keptIndex = projection.entries.findIndex((entry) => entry.sourceEntry.id === firstKeptEntryId);
+  return keptIndex < 0 ? undefined : projection.entries.slice(keptIndex);
+}
+
+/** Pi's context handlers see only non-system messages; Pi carries system messages separately. */
+export function withoutSystemMessages<T extends { readonly role: string }>(messages: readonly T[]): T[] {
+  return messages.filter((message) => message.role !== "system");
+}
+
+function conversationMessages(entries: readonly ProjectedSessionEntry[]): AgentMessage[] {
+  // appendCompaction snapshots system messages separately from the retained conversation.
+  return withoutSystemMessages(entries.flatMap((entry) => entry.messages));
+}
+
+export function keptMessages(branchEntries: readonly SessionEntry[], firstKeptEntryId: string): AgentMessage[] {
+  const retained = retainedEntries(branchEntries, branchEntries.at(-1)?.id ?? null, firstKeptEntryId);
+  if (!retained) throw new Error("Pi compaction cut point is not present in the active context");
+  return conversationMessages(retained);
+}
+
+function normalizeLegacyFingerprints(
+  entries: readonly SessionEntry[],
+  entry: CompactionEntry,
+  details: CodexCheckpointDetails,
+): CodexCheckpointDetails {
+  // Validate at the checkpoint's parent, never against later context edits.
+  const retained = retainedEntries(entries, entry.parentId, entry.firstKeptEntryId);
+  if (!retained) return details;
+  const canonical = conversationMessages(retained);
+  const matches = (messages: readonly AgentMessage[], fingerprint: (message: AgentMessage) => string) =>
+    messages.length === details.keptMessageFingerprints.length &&
+    messages.every((message, index) => fingerprint(message) === details.keptMessageFingerprints[index]);
+  if (matches(canonical, fingerprintMessage)) return details;
+  // V1 did not record its locale. Only normalize old hashes when the old ordering proves an exact match.
+  const legacyFingerprint = (message: AgentMessage) => digestMessage(message, (left, right) => left.localeCompare(right));
+  const raw = retained.flatMap((item) => sessionEntryToContextMessages(item.sourceEntry));
+  if (!matches(canonical, legacyFingerprint) && !matches(raw, legacyFingerprint)) return details;
+  return { ...details, keptMessageFingerprints: canonical.map(fingerprintMessage) };
+}
+
+export function latestCheckpoint(
+  entries: readonly SessionEntry[],
+): { entry: CompactionEntry<CodexCheckpointDetails>; details: CodexCheckpointDetails } | undefined {
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const entry = entries[index];
+    if (entry.type !== "compaction") continue;
+    // A checkpoint's ancestors are immutable, so its normalized details are stable per entry.
+    let details = checkpoints.get(entry);
+    if (details === undefined) {
+      const parsed = parseCheckpointDetails(entry.details);
+      details = parsed ? normalizeLegacyFingerprints(entries, entry, parsed) : null;
+      checkpoints.set(entry, details);
+    }
+    return details ? { entry: entry as CompactionEntry<CodexCheckpointDetails>, details } : undefined;
+  }
+  return undefined;
+}
+
+export function projectCheckpointContext(
+  messages: readonly AgentMessage[],
+  details: CodexCheckpointDetails,
+): AgentMessage[] | undefined {
+  const summary = fallbackSummary(details.checkpointId);
+  const summaryIndex = messages.findIndex(
+    (message) => message.role === "compactionSummary" && message.summary === summary,
+  );
+  if (summaryIndex < 0) return undefined;
+  const keptStart = summaryIndex + 1;
+  const keptEnd = keptStart + details.keptMessageFingerprints.length;
+  if (keptEnd > messages.length) return undefined;
+  for (let index = keptStart; index < keptEnd; index++) {
+    if (
+      fingerprintMessage(messages[index]) !== details.keptMessageFingerprints[index - keptStart]
+    ) {
+      return undefined;
+    }
+  }
+  return [
+    ...messages.slice(0, summaryIndex),
+    markerMessage(details.checkpointId, messages[summaryIndex].timestamp),
+    ...messages.slice(keptEnd),
+  ];
+}
+
+/**
+ * Project a full transcript the way Pi sends a request whose context handler changed messages:
+ * handlers see only non-system messages, and Pi collapses the system messages into one head.
+ */
+export function projectCheckpointRequest(
+  messages: readonly AgentMessage[],
+  details: CodexCheckpointDetails,
+): AgentMessage[] | undefined {
+  const projected = projectCheckpointContext(withoutSystemMessages(messages), details);
+  if (!projected) return undefined;
+  const head = getCurrentSystemMessage(messages.filter((message): message is Message => message.role === "system"));
+  return head ? [head, ...projected] : projected;
+}
+
+export function createCheckpointDetails(input: {
+  identity: ProviderIdentity;
+  replacementHistory: JsonObject[];
+  keptMessages: readonly AgentMessage[];
+  checkpointId?: string;
+  createdAt?: string;
+}): CodexCheckpointDetails {
+  const details: CodexCheckpointDetails = {
+    kind: CHECKPOINT_KIND,
+    version: CHECKPOINT_VERSION,
+    checkpointId: input.checkpointId ?? randomUUID(),
+    ...input.identity,
+    protocol: REMOTE_COMPACTION_PROTOCOL,
+    replacementHistory: structuredClone(input.replacementHistory),
+    keptMessageFingerprints: input.keptMessages.map(fingerprintMessage),
+    createdAt: input.createdAt ?? new Date().toISOString(),
+  };
+  const parsed = parseCheckpointDetails(details);
+  if (!parsed) throw new Error("Created an invalid Codex checkpoint");
+  return parsed;
+}