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 状态；切换后应使用新 Session。配置不写回 settings.json，默认 soft/hard/target 比例为 72%/90%/55%。
• Context Authority 是 compaction 唯一生产投影者。普通 Provider、Codex native、/context、/compaction-status 和 footer 必须消费同一个不可变 projection snapshot；pi-minimal-footer 优先显示同一 effective usage，snapshot 尚未建立时才回退宿主原始 usage；background worker 不得在 Provider 请求中被 await。
• pi-compaction 负责已经进入 Session 的历史投影，与 Context Mode 的输入隔离职责互补。首次 Session hydration 允许一次完整扫描；后续普通 context hot path 必须复用不可变 snapshot 或只处理 delta，不得调用 summarizer、写 Session 或重新构建完整 branch。
• 已闭合工具结果先同步生成保留工具名、参数、状态、首尾证据和 source key 的有界确定性 stub；大于 semantic.minInputChars 的结果再进入单 Session 有界后台语义 worker。后台结果只在安全事件边界提交，陈旧 hash 必须丢弃，Provider 请求不得等待后台摘要。
• Segment custom entry 只能保存摘要、hash 和 source reference，不得复制完整原始工具输出。context_tree_query 恢复结果必须有界，native checkpoint 的 portable summary 也必须有界。
• effective token 默认使用 Provider usage-backed baseline 加 projected delta；无可靠 baseline 时使用带上下界的估算。Pi Core raw threshold 只负责唤醒，只有 effective lower bound 达到 hardRatio 才执行 threshold compaction；manual 与 overflow 不得被阻断。
• Codex native compaction 必须直接消费当前 projection 生成的 ResponseItems，不得从 raw branch 重建输入；native checkpoint 同时保存有界 portable summary 供模型或 Provider 切换。
• 原生远程压缩限定为 openai-codex + openai-codex-responses 与 sub-api + openai-responses，默认在 turn boundary 达到 effective 下界 90% 时触发。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。