my-pi/pi-compaction/AGENTS.md

my-pi 维护约定（pi-compaction）

• 扩展入口是 pi-compaction/index.ts，遮蔽规划、投影索引、遮蔽台账、服务与 Codex native 实现在 src/，测试位于 test/，双上游来源记录是 UPSTREAM.md。
• 根包必须通过 file:./pi-compaction 提供依赖并直接加载源码；不得重新声明或加载 pi-condense、npm @ogulcancelik/pi-codex-compaction 或 npm pi-context-view。
• pi-compaction 只支持自己的 version 1 记录和 config/pi-compaction.json 配置，不读取或迁移旧 context-prune-*、contextPrune、openai-codex-native-compaction 或旧 segment-summary 状态；切换后应使用新 Session。配置不写回 settings.json。
• Context Authority 是 compaction 唯一生产投影者。普通 Provider、Codex native、/context、/compaction-status 和 footer 必须消费同一个不可变 projection snapshot；pi-minimal-footer 优先显示同一 effective usage，snapshot 尚未建立时才回退宿主原始 usage。
• pi-compaction 负责已经进入 Session 的历史投影，与 pi-overflow 的新结果入口截断职责互补。首次 Session hydration 允许一次完整扫描；后续普通 context hot path 必须复用不可变 snapshot 或只处理 delta，不得调用 summarizer、写 Session 或重新构建完整 branch。
• L2 遮蔽只用 Pi 原生 context_edit（{ type: "context_edit", targetId, replacement }）处理保护窗口外的旧 toolResult：成批提交、受 trigger/target 回差与 minClearTokens 约束，不逐条即时替换；不为遮蔽写 segment-summary 等 custom entry，原始条目、UI 与导出保持不变。
• 不得改写最近 keepRecentTurns 轮；不得遮蔽 user/assistant 消息、excludeTools 中的工具、SKILL.md 的 read 结果、已遮蔽或已省略的条目、以及小于 minEntryTokens 的结果。
• 遮蔽占位符必须确定性、单行、以 MASK_PREFIX（"[pi-compaction] Earlier "）开头，并在文本中指向 context_tree_query 恢复；context_tree_query 与 native checkpoint 的 portable summary 都必须有界。被遮蔽的 toolResult 若带 details.overflow.id（pi-overflow 已存原文），占位符末尾追加 overflow_query 提示——只读该公开字段，不得 import pi-overflow 内部实现。
• L3 整段摘要只能从空闲的 agent_settled 通过 ctx.compact 触发（ctx.compact 会中止当前运行，非空闲时调用会破坏运行）；同一 leaf 不重复触发。阈值以绝对 token 计并受窗口比例约束（effectiveThreshold = min(tokens, floor(ratio × contextWindow))）。
• context 钩子不得改写消息——非 checkpoint 路径只更新 snapshot 并返回 undefined；唯一例外是 native checkpoint 路径：checkpoint 之后的条目在投影时必须应用各 target 最新的 context_edit（null 省略、字符串规范成 text block），因为 sessionEntryToContextMessages 不处理 edits。
• session_before_compact 只负责生成 portable/native 摘要，不得按自身阈值取消 Pi 的压缩（Pi 的 contextTokens > window - reserveTokens 是最终安全网）。
• effective token 默认使用 Provider usage-backed baseline 加 projected delta；无可靠 baseline 时使用带上下界的估算。遮蔽台账在 session_start / session_tree / session_compact 从当前 branch 的 context_edit 条目重建，指标暴露 maskedResults 与 reclaimedTokens。
• Codex native compaction 必须直接消费当前 projection 生成的 ResponseItems，不得从 raw branch 重建输入；native checkpoint 同时保存有界 portable summary 供模型或 Provider 切换。
• 原生远程压缩限定为 openai-codex + openai-codex-responses 与 sub-api + openai-responses，默认由 L3 阈值或 Pi 自身阈值触发。src/native-provider.ts 统一资格与传输选择：Codex 保留原 endpoint/JWT/account ID；SubAPI 从显式 baseUrl 解析公共 /responses，使用配置的 API key 和请求头，不解析 ChatGPT account ID、不硬编码网关域名，也不调用独立 /responses/compact。两者复用 projection、compaction_trigger、SSE 结果、native checkpoint 恢复和 portable 模型切换摘要；SubAPI 部署须支持原生 compaction v2。普通聊天支持不代表压缩支持，失败回退 Pi，不自动改写用户模型配置。
• SubAPI 原生压缩认证必须保留非空显式 Authorization（大小写不敏感）的优先级；没有该头时才使用非空 API key 生成 Bearer，均缺失时可接受非空 cf-aig-authorization 代理认证头。不得要求 header-only 配置额外提供假 API key，也不得生成 Bearer undefined；空白或缺失凭据在网络请求前拒绝并回退 Pi。Codex 仍必须提供有效 JWT，不能用请求头绕过。
• 同步 Codex 协议代码必须从官方 ogulcancelik/pi-extensions 明确 commit 移植并保留对应 MIT 许可证；不得从 npm tarball、缓存、node_modules 或构建产物导入。

验证

• 在本目录内至少运行 npm test、npm run check 和 npm pack --dry-run --json；涉及依赖、加载入口、context writer、footer 或 observer 时还要验证根 npm install 幂等、锁文件仅包含预期本地 link 变化、根扩展联合加载、性能回归，以及实际 packed 根 tarball 的隔离安装/加载。
• 修改 projection、token accounting、遮蔽规划/台账、threshold、checkpoint、模型切换或恢复索引后，至少运行 npm test、npm run check、npm pack --dry-run --json、根扩展联合加载、packed 根 tarball 隔离加载和性能回归。性能门禁为 cache-hit P95 <2ms、delta projection P95 <10ms，普通 hot path 不得扫描完整 branch。