pi-openai-toolkit 0.12.0 → 0.13.0

package/NOTICE

@@ -53,3 +53,31 @@ 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 Remote Context management implementation in src/context-management/ was
+adapted from @howaboua/pi-codex-conversion@3.0.29 at source commit
+7021ae48e8efe36a3becc5830d529696ff798e5e.
+
+Upstream copyright and license notice:
+
+MIT License
+
+Copyright (c) 2026 Igor Warzocha
+
+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

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>OpenAI-focused toolkit for <a href="https://github.com/earendil-works/pi">Pi</a>: Remote Compaction v2, Hosted Web Search, Native Image Generation &amp; Model-Reviewed Auto Mode</strong>
+  <strong>OpenAI-focused toolkit for <a href="https://github.com/earendil-works/pi">Pi</a>: Codex Remote Context Management, Remote Compaction v2, Hosted Web Search, Native Image Generation &amp; Model-Reviewed Auto Mode</strong>
 </p>
 
 <p align="center">
@@ -12,7 +12,7 @@
 
 `pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.85.1)**. It bundles five extensions designed for OpenAI Responses endpoints:
 
-1. **Remote Responses Compaction v2** (`extensions/compaction.ts`): Server-side opaque context compaction using the `remote_compaction_v2` SSE streaming protocol. Preserves context fidelity without lossy text re-summarization.
+1. **Remote Responses Compaction v2 + Codex Remote Context Management** (`extensions/compaction.ts`): Two long-context strategies. Remote Context management (`compaction.contextManagement: "remote"`) ports Codex's native window system to Pi: a no-summary `new_context` rollover gated on a real notes checkpoint, cross-window `history` / `notes` tools with encrypted argument transport, `get_context_remaining` budgeting, and configurable context reminders — over native Codex OAuth or an allowlisted Codex-compatible gateway. When it is off, the toolkit falls back to server-side opaque `remote_compaction_v2` SSE compaction, which preserves context fidelity without lossy text re-summarization.
 2. **Model-Scoped Web Search** (`extensions/web-search.ts`): Toolkit-owned hosted Web Search for an exact `provider/model-id` allowlist configured with `webSearch.models`, across the supported `openai-responses` and `openai-codex-responses` APIs.
 3. **Native Image Generation** (`extensions/image-generation.ts`): A sequential local tool backed by the hosted Responses `image_generation` tool. It supports text-to-image and explicit local-reference edits while keeping binary image data out of session history.
 4. **Model-Reviewed Auto Mode** (`extensions/auto-mode.ts`): Pi does not prompt before running tools. Auto mode adds a gate on state-changing tool calls and lets a reviewer model you configure approve or deny each one, so the agent keeps working without interrupting you.
@@ -99,6 +99,8 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 {
   "compaction": {
     "enabled": true,
+    "contextManagement": "off",
+    "codexGatewayModels": [],
     "allowCompactionContinuityBreak": false,
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
     "nativeFallback": {
@@ -131,7 +133,7 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ],
-    "reviewerModel": "uwoacrimson/gpt-5.6-sol",
+    "reviewerModel": "uwoacrimson/gpt-5.6-luna",
     "gate": "side-effect",
     "extraTools": [
       "openai_generate_image"
@@ -165,18 +167,45 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 
 #### `compaction`
 
-- `enabled` (*boolean*, default: `true`): Enable or disable Remote Compaction.
+- `enabled` (*boolean*, default: `true`): Enable or disable toolkit compaction hooks.
+- `contextManagement` (*`"off" | "remote"`*, default: `"off"`): Opt into Codex Remote Context management. `"remote"` is active for the native `openai-codex` / `openai-codex-responses` route, or for an exact entry in `codexGatewayModels` whose model resolves to `uwoacrimson` / `openai-responses`. Native mode reuses Pi's existing Codex OAuth through `ModelRegistry`; gateway mode uses the configured data-plane API key and does not derive or forward a local Codex account ID. Remote windows use Codex history/notes, retain the full Pi JSONL session, and do not generate ordinary summaries. While active, this feature owns context rollover and disables this package's `remote_compaction_v2` request. Set it back to `"off"` or clear the allowlist to roll back to the existing compaction behavior. Remote backend failures are surfaced; they never silently fall back to Local context management.
+- `codexGatewayModels` (*string[]*, default: `[]`): Exact `provider/model-id` entries allowed to use the NEWapi/CPA Codex gateway, for example `"uwoacrimson/gpt-5.6-luna"`. Entries are opt-in, trimmed, and matched exactly; the gateway sends the bare model ID in `X-Codex-Model` and keeps the configured `/v1` base URL. An empty list disables gateway Remote Context.
 - `allowCompactionContinuityBreak` (*boolean*, default: `false`): When `true`, allows restarting a fresh native opaque compaction chain from Pi's current session text if the latest compaction was made by another strategy (e.g. text summary).
 - `remoteCompactModel` (*string | null*, default: `null`): Model formatted as `provider/model-id` used only for the synthetic `remote_compaction_v2` request. Pi's active session model is not switched and resumes normal requests after compaction. The override must resolve to the same effective base URL as the active model; provider, Responses API identifier, and model may differ. `null` preserves the current same-model path.
 - `nativeFallback.enabled` (*boolean*, default: `true`): Master switch for toolkit-driven native compaction with an explicit summary model. It never touches the remote chain: `remote_compaction_v2` is still attempted and still wins when it succeeds. When `false`, only the post-failure native step is skipped, so every fallback falls straight through to Pi's own default compaction with the active model.
 - `nativeFallback.model` (*string | null*, default: `null`): Summary model formatted as `provider/model-id` (e.g. `"openai/gpt-4o-mini"`) used **only** when the active model cannot use remote v2 at all (non-Responses API, or an API excluded by `responsesApis`). It is never consulted once a remote request was attempted, and `null` means the active model runs Pi's default compaction path.
 - `nativeFallback.thinkingLevel` (*string*, default: `"off"`): Reasoning / thinking level passed to Pi's native `compact()` whenever this extension supplies the model (`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`).
-- `responsesApis` (*string[]*): Narrow the supported remote compaction API identifiers (subset of `["openai-responses", "openai-codex-responses"]`).
+- `responsesApis` (*string[]*): Narrow the supported remote compaction API identifiers (subset of `["openai-responses", "openai-codex-responses"]`). This setting applies only when `contextManagement` is `"off"`.
 - `notifyOnLoad` (*boolean*, default: `false`): Show a notification banner on Pi startup.
 - `debug` (*boolean*, default: `false`): Output diagnostics and write execution artifacts to disk.
 - `logProviderPayloads` / `logCompactResponses` (*boolean*, default: `false`): Write raw provider request payloads and compact SSE event bodies to artifacts.
-- `redactSensitiveData` (*boolean*, default: `true`): Apply full sensitive-value redaction to debug artifacts. Authorization credentials, API keys/tokens, and opaque `encrypted_content` are always redacted even when this option is `false`.
+- `redactSensitiveData` (*boolean*, default: `true`): Apply full sensitive-value redaction to debug artifacts. Authorization credentials, API keys/tokens, Codex account IDs, and opaque `encrypted_content` / `encrypted_output` are always redacted even when this option is `false`.
 - `artifactRoot` (*string*): Directory root for diagnostic artifacts. Relative paths resolve against the config directory.
+- `contextReminderThresholdPercent` (*integer*, default: `5`, range `0`-`100`): Remote Context only. When tokens remaining in the current window drop below this percentage of the context window, the toolkit injects a checkpoint reminder once per window; at `0` reminders are disabled (the exhausted-window fallback still fires). Set it comfortably above Pi's native reserve band so the model gets a chance to roll the window over before the native threshold is reached.
+
+### Recommended Remote Context configuration
+
+To run Codex Remote Context management on this gateway setup:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "contextManagement": "remote",
+    "codexGatewayModels": ["uwoacrimson/gpt-6-astra"],
+    "contextReminderThresholdPercent": 10
+  }
+}
+```
+
+Two operational notes:
+
+- **Disable Pi's native compaction for Remote-managed sessions.** While `contextManagement` is `"remote"` and the model is covered (native Codex, or listed in `codexGatewayModels`), the toolkit already cancels every Pi-native compaction attempt — threshold, manual `/compact`, and overflow — so no lossy summary can slip in behind its back. If you also want belt-and-braces at the host level, set `"compaction": { "enabled": false }` in Pi's `~/.pi/agent/settings.json`; models outside the Remote coverage still compact normally with Pi's own policy either way.
+- **`new_context` cannot discard unsaved state silently.** The tool refuses to roll over unless the current window contains a *successful* `notes` `append_to_file` / `write_file` (read-only notes calls and failed writes do not count; the check is rebuilt from the session branch, so it survives restarts and resumes). `force: true` bypasses the gate for explicit user-authorized discards, and the toolkit's own exhausted-context fallback path bypasses it automatically.
+
+#### Remote Context protocol notes
+
+When `compaction.contextManagement` is `"remote"`, the toolkit activates `new_context`, `get_context_remaining`, `history`, and `notes` for the native Codex route or an exact allowlisted gateway model. History and notes use the alpha `alpha/history/v2/*` and `alpha/notes/v2/*` endpoints, including encrypted argument policy headers for search and note writes. `new_context` accepts an optional `force` flag; without a successful notes checkpoint in the current window it refuses unless `force` is set (see Recommended Remote Context configuration). Gateway requests carry the same bounded session ID, affinity scope, and bare model hint as live Responses requests; the gateway never receives local OAuth credentials or account cookies. The request carries the current window and turn metadata; timeout, abort, non-2xx, malformed JSON, authentication, and protocol failures are explicit tool errors. For covered models the toolkit also cancels Pi's native compaction while the Remote runtime is inactive, so no lossy summary is produced behind its back; fix the activation reason shown in the notification instead. The protocol is based on `@howaboua/pi-codex-conversion@3.0.29` source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`; these alpha endpoints may change and the endpoint/header fixtures must be updated together.
 
 #### `webSearch`
 
@@ -219,6 +248,17 @@ Auto mode is opt-in through the empty-by-default `models` allowlist because it a
 
 ## Core Mechanics
 
+### 0. Codex Remote Context Management
+
+When `compaction.contextManagement` is `"remote"` and the session's model is covered — native `openai-codex` / `openai-codex-responses`, or an exact `provider/model-id` entry in `codexGatewayModels` resolving to `uwoacrimson` / `openai-responses` — the toolkit replaces summarization-based compaction with Codex's native context-window lifecycle:
+
+- **Window identity.** `session_start` initializes a context window (first / current / previous window id, window number) and persists each boundary as a `codex-context-window` custom message in the Pi session, replayed on resume and reconstructed after forks. Every live request carries the window and turn identity through `x-codex-window-id` / `x-codex-turn-metadata`.
+- **No-summary rollover.** `new_context` installs a fresh window and trims the previous one from the model context; nothing is re-summarized, so no lossy text survives in place of the conversation. The old turns remain retrievable server-side through `history`.
+- **Checkpoint gate.** A rollover requires a successful `notes` write inside the current window, verified against the persisted session branch; without it, `new_context` refuses and tells the model to checkpoint first. This is a hard guard against the failure mode where a notes backend is down and a rollover silently discards live working state. `force: true` and the exhausted-context fallback path are the only ways past the gate, and the fallback message instructs a single last notes write before rollover.
+- **Cross-window memory.** `history` (`list_windows`, `list_items`, `read_item`, `search_contents`) and `notes` (`list_files_by_prefix`, `read_file`, `search_contents`, `append_to_file`, `write_file`) hit the alpha Codex backend endpoints with encrypted tool arguments and encrypted result handling; note paths resolve under the session agent (`/root/notes/...`). After a rollover, a server-side thread hint points the model at the notes that hold the live task state.
+- **Budget.** `get_context_remaining` reports the remaining window budget; `contextReminderThresholdPercent` injects the checkpoint reminder once per window as remaining tokens fall below the configured percentage of the context window.
+- **Ownership of compaction.** While configured for a covered model, the toolkit owns all compaction events: Pi-native compaction is cancelled even when the Remote runtime is inactive (the reason is surfaced as a notification, e.g. a tool-name conflict or OAuth resolution failure), and `remote_compaction_v2` is never sent. Set `contextManagement` back to `"off"` or clear the allowlist to restore the previous behavior.
+
 ### 1. Remote Compaction v2 Protocol
 
 Instead of legacy JSON endpoints (`POST /responses/compact`), this toolkit implements the **`remote_compaction_v2`** protocol over standard streaming Responses:

package/README_zh.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>专为 <a href="https://github.com/earendil-works/pi">Pi</a> 打造的 OpenAI 增强工具包：远端无损压缩 v2、原生托管联网搜索、图像生成与模型审批 Auto 模式</strong>
+  <strong>专为 <a href="https://github.com/earendil-works/pi">Pi</a> 打造的 OpenAI 增强工具包：Codex 远端上下文管理、远端无损压缩 v2、原生托管联网搜索、图像生成与模型审批 Auto 模式</strong>
 </p>
 
 <p align="center">
@@ -12,7 +12,7 @@
 
 `pi-openai-toolkit` 是专为 **Pi (>= 0.85.1)** 打造的 OpenAI 增强工具包，集成了五项针对 OpenAI Responses 协议的扩展：
 
-1. **远端无损压缩 (Remote Compaction v2)** (`extensions/compaction.ts`): 基于 `remote_compaction_v2` SSE 流式协议实现的服务端密文无损会话压缩，彻底告别会话变长后丢失细节的文本二次摘要。
+1. **Codex 远端上下文管理 + 远端无损压缩 v2** (`extensions/compaction.ts`): 两套长上下文策略。远端上下文管理（`compaction.contextManagement: "remote"`）把 Codex 原生窗口体系移植到 Pi：无摘要 `new_context` 换窗（附真实 notes  checkpoint 硬门禁）、跨窗口 `history` / `notes` 工具（加密参数传输）、`get_context_remaining` 预算查询与可配置上下文提醒——支持原生 Codex OAuth 或白名单 Codex 兼容 Gateway。关闭时则由 `remote_compaction_v2` SSE 协议提供服务端密文无损压缩，彻底告别会话变长后丢失细节的文本二次摘要。
 2. **按模型启用的联网搜索** (`extensions/web-search.ts`): 通过 `webSearch.models` 精确匹配 `provider/model-id`，由 Toolkit 为符合条件的 `openai-responses` 与 `openai-codex-responses` 会话提供并拥有原生联网搜索。
 3. **原生图像生成** (`extensions/image-generation.ts`): 注册由 Responses 托管 `image_generation` 工具驱动的本地顺序工具，支持文生图和显式本地参考图编辑，同时避免把图像二进制写入会话历史。
 4. **模型审批 Auto 模式** (`extensions/auto-mode.ts`): Pi 默认不会为工具调用弹出审批确认。Auto 模式为改变状态的工具调用加上一道审批门，由你指定的审批模型判定放行或拦截，让 Agent 不必停下来等你确认也能继续推进。
@@ -97,6 +97,8 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 {
   "compaction": {
     "enabled": true,
+    "contextManagement": "off",
+    "codexGatewayModels": [],
     "allowCompactionContinuityBreak": false,
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
     "nativeFallback": {
@@ -129,7 +131,7 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ],
-    "reviewerModel": "uwoacrimson/gpt-5.6-sol",
+    "reviewerModel": "uwoacrimson/gpt-5.6-luna",
     "gate": "side-effect",
     "extraTools": [
       "openai_generate_image"
@@ -163,18 +165,45 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 
 #### `compaction`（压缩配置）
 
-- `enabled` (*boolean*, 默认 `true`): 是否启用远端无损压缩。
+- `enabled` (*boolean*, 默认 `true`): 是否启用 Toolkit 的压缩 Hook。
+- `contextManagement` (*`"off" | "remote"`*，默认 `"off"`): 可选的 Codex Remote Context 管理。`"remote"` 可用于原生 `openai-codex` / `openai-codex-responses` 路线，或 `codexGatewayModels` 中精确白名单项对应的 `uwoacrimson` / `openai-responses` 模型。原生模式复用 Pi 已有的 Codex OAuth，通过 `ModelRegistry` 获取；Gateway 模式使用配置的数据面 API key，不推导也不转发本地 Codex account ID。Remote 窗口保留完整 Pi JSONL，不生成普通摘要，并使用 Codex history/notes。开启后由它独占上下文窗口切换，因此不会发送本包现有的 `remote_compaction_v2` 请求。设回 `"off"` 或清空白名单即可回滚到原有压缩行为；Remote 后端失败会明确报错，不会静默切换到 Local。
+- `codexGatewayModels` (*string[]*，默认 `[]`): 允许使用 NEWapi/CPA Codex Gateway 的精确 `provider/model-id` 项，例如 `"uwoacrimson/gpt-5.6-luna"`。条目会去空格并精确匹配；转发时 `X-Codex-Model` 使用不带 provider 前缀的模型 ID，并保留配置中的 `/v1` Base URL。空数组表示关闭 Gateway Remote Context。
 - `allowCompactionContinuityBreak` (*boolean*, 默认 `false`): 若最近一次历史压缩由其他方式（如文本摘要）生成，设为 `true` 允许直接从当前有效文本上下文重建密文压缩链。
 - `remoteCompactModel` (*string | null*, 默认 `null`): 仅用于 synthetic `remote_compaction_v2` 请求的模型，格式为 `"provider/model-id"`。Pi 不会切换当前会话模型，压缩完成后仍由原模型继续正常请求。覆盖模型必须与当前模型使用相同的实际生效 Base URL；Provider、Responses API 标识符和模型本身可以不同。为 `null` 时保持当前模型执行远端压缩的原有行为。
 - `nativeFallback.enabled` (*boolean*, 默认 `true`): Toolkit 用显式摘要模型跑原生压缩的总开关。它不影响远端链路：`remote_compaction_v2` 照常被尝试，成功时照常生效。设为 `false` 只跳过失败后的那一步原生压缩，因此所有降级都直接交给 Pi 默认的当前模型压缩。
 - `nativeFallback.model` (*string | null*, 默认 `null`): 摘要模型，格式为 `"provider/model-id"`（例如 `"openai/gpt-4o-mini"`），**仅**用于根本无法走远端 v2 的当前模型（非 Responses API，或 API 被 `responsesApis` 排除）。远端请求已经发出过的情境不会读这个字段；为 `null` 时由当前活动模型走 Pi 默认压缩路径。
 - `nativeFallback.thinkingLevel` (*string*, 默认 `"off"`): 由本扩展指定模型时，传给 Pi 原生 `compact()` 的思考级别。
-- `responsesApis` (*string[]*): 允许尝试远端压缩的 API 标识符子集（从 `["openai-responses", "openai-codex-responses"]` 中选定）。
+- `responsesApis` (*string[]*): 允许尝试远端压缩的 API 标识符子集（从 `["openai-responses", "openai-codex-responses"]` 中选定）。仅在 `contextManagement` 为 `"off"` 时影响压缩路径。
 - `notifyOnLoad` (*boolean*, 默认 `false`): Pi 启动加载时是否弹出气泡提示。
 - `debug` (*boolean*, 默认 `false`): 是否开启调试模式并记录诊断日志。
 - `logProviderPayloads` / `logCompactResponses` (*boolean*, 默认 `false`): 是否在 Artifacts 中记录完整的 Provider 请求与 SSE 流事件体。
-- `redactSensitiveData` (*boolean*, 默认 `true`): 对调试日志应用完整的敏感值脱敏。即使设为 `false`，Authorization 凭据、API Key/Token 和 `encrypted_content` 密文也始终会被替换为 `[REDACTED]`。
+- `redactSensitiveData` (*boolean*, 默认 `true`): 对调试日志应用完整的敏感值脱敏。即使设为 `false`，Authorization 凭据、API Key/Token、Codex account ID 以及 `encrypted_content` / `encrypted_output` 密文也始终会被替换为 `[REDACTED]`。
 - `artifactRoot` (*string*): 诊断日志存储根目录，支持 `~/` 路径。
+- `contextReminderThresholdPercent` (*integer*, 默认 `5`，范围 `0`-`100`): 仅用于 Remote Context。当前窗口剩余 token 低于上下文窗口该百分比时，Toolkit 每窗口注入一次 checkpoint 提醒；设为 `0` 关闭提醒（窗口耗尽兜底仍照旧生效）。建议设在明显高于 Pi 原生 reserve 余量的位置，让模型在撞上原生阈值前有机会主动换窗。
+
+### Remote Context 推荐配置
+
+在本网关环境下启用 Codex 远端上下文管理：
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "contextManagement": "remote",
+    "codexGatewayModels": ["uwoacrimson/gpt-6-astra"],
+    "contextReminderThresholdPercent": 10
+  }
+}
+```
+
+两点运行提示：
+
+- **Remote 覆盖的会话请确保 Pi 原生压缩不会插队。** 只要 `contextManagement` 为 `"remote"` 且模型在覆盖范围内（原生 Codex 或列入 `codexGatewayModels`），Toolkit 就会取消所有 Pi 原生压缩尝试——阈值触发、手动 `/compact`、溢出恢复全部拦下，不会有有损摘要背地里插入。如果想再加一道保险，可在 Pi 的 `~/.pi/agent/settings.json` 里设 `"compaction": { "enabled": false }`；覆盖范围外的模型无论如何都会正常走 Pi 自己的压缩。
+- **`new_context` 不会静默丢弃未保存状态。** 当前窗口内没有*成功的* `notes` `append_to_file` / `write_file` 时，换窗会被拒绝（只读操作和失败的写入不算；检查从会话分支重建，重启/resume 后依然有效）。`force: true` 供用户明确授权丢弃时绕过门禁；Toolkit 自己的窗口耗尽兜底路径会自动绕过。
+
+#### Remote Context 协议说明
+
+开启 `compaction.contextManagement: "remote"` 后，本包会在原生 Codex 路线或精确白名单 Gateway 模型上激活 `new_context`、`get_context_remaining`、`history` 和 `notes`。History/notes 使用 alpha `alpha/history/v2/*` 与 `alpha/notes/v2/*` 端点；搜索和笔记写入会携带加密参数策略 Header。`new_context` 支持可选 `force` 参数；当前窗口没有成功的 notes checkpoint 时，除非设置 `force`，否则拒绝换窗（见上方推荐配置）。Gateway 请求与实时 Responses 请求使用相同的有界 session ID、affinity scope 和不带 provider 前缀的模型提示；Gateway 不会收到本地 OAuth 凭据或 account cookie。请求带有窗口和 turn metadata；超时、取消、非 2xx、非法 JSON、认证和协议错误都会明确返回工具错误。对覆盖范围内的模型，即使 Remote 运行时未激活，Toolkit 也会取消 Pi 原生压缩，不会产生有损摘要；请按通知里的原因修复激活问题（如工具名冲突、OAuth 解析失败）。协议参考 `@howaboua/pi-codex-conversion@3.0.29` 的 source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`；这些 alpha 端点变化时，需要同步更新端点、Header 和 fixture 测试。
 
 #### `webSearch`（联网搜索配置）
 
@@ -217,6 +246,17 @@ Auto 模式需要显式启用（`models` 默认为空），因为它相当于允
 
 ## 核心工作原理解析
 
+### 0. Codex 远端上下文管理（Remote Context Management）
+
+当 `compaction.contextManagement` 为 `"remote"` 且会话模型在覆盖范围内（原生 `openai-codex` / `openai-codex-responses`，或 `codexGatewayModels` 中精确匹配的 `uwoacrimson` / `openai-responses` 条目），Toolkit 会用 Codex 原生上下文窗口体系取代摘要式压缩：
+
+- **窗口身份。** `session_start` 初始化上下文窗口（first / current / previous window id、窗口编号），每次换窗以 `codex-context-window` 自定义消息持久化到 Pi 会话，resume 可回放、fork 后重建；每次实时请求通过 `x-codex-window-id` / `x-codex-turn-metadata` 携带窗口与 turn 身份。
+- **无摘要换窗。** `new_context` 安装新窗口并把旧窗口从模型上下文裁剪掉，不做任何再摘要，因此不会有有损文本取代对话；旧轮次仍可通过服务端 `history` 取回。
+- **Checkpoint 硬门禁。** 换窗前必须存在当前窗口内成功的 `notes` 写入，校验基于持久化会话分支重建，重启/resume 后依然有效；不满足时 `new_context` 直接拒绝并提示先 checkpoint。这正是针对“notes 后端故障时换窗静默丢失工作状态”的硬拦截。`force: true` 与窗口耗尽兜底是仅有的两条绕过路径，兜底消息会要求先做最后一次 notes 写入再换窗。
+- **跨窗口记忆。** `history`（`list_windows`、`list_items`、`read_item`、`search_contents`）与 `notes`（`list_files_by_prefix`、`read_file`、`search_contents`、`append_to_file`、`write_file`）调用 alpha Codex 后端端点，工具参数与结果均按加密协议处理；notes 路径解析到会话 agent 目录下（`/root/notes/...`）。换窗后服务端 thread hint 会指向持有当前任务状态的 notes。
+- **预算。** `get_context_remaining` 报告当前窗口剩余预算；`contextReminderThresholdPercent` 控制剩余 token 低于窗口百分比时每窗口一次的 checkpoint 提醒。
+- **压缩独占。** 对覆盖模型，Toolkit 拥有全部压缩事件：即使 Remote 运行时未激活也会取消 Pi 原生压缩（未激活原因以通知明确报出，如工具名冲突、OAuth 解析失败），`remote_compaction_v2` 不会发送。设回 `"off"` 或清空白名单即恢复原有行为。
+
 ### 1. Remote Compaction v2（远端密文压缩）
 
 摒弃了老旧且不稳定的 `POST /responses/compact` JSON 端点，采用最新 **`remote_compaction_v2`** 标准流式协议：

package/package.json

@@ -1,116 +1,126 @@
-{
-  "name": "pi-openai-toolkit",
-  "version": "0.12.0",
-  "private": false,
-  "type": "module",
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction, native Web Search, native image generation, and model-reviewed auto mode.",
-  "author": "awoaCrim and contributors",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/awoaCrim/pi-openai-toolkit.git"
-  },
-  "bugs": {
-    "url": "https://github.com/awoaCrim/pi-openai-toolkit/issues"
-  },
-  "homepage": "https://github.com/awoaCrim/pi-openai-toolkit#readme",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "openai",
-    "compaction",
-    "web-search",
-    "image-generation",
-    "auto-mode",
-    "codex",
-    "responses"
-  ],
-  "pi": {
-    "extensions": [
-      "./extensions/compaction.ts",
-      "./extensions/web-search.ts",
-      "./extensions/image-generation.ts",
-      "./extensions/auto-mode.ts",
-      "./extensions/codex-astra.ts"
-    ]
-  },
-  "files": [
-    "extensions/compaction.ts",
-    "extensions/web-search.ts",
-    "extensions/image-generation.ts",
-    "extensions/auto-mode.ts",
-    "src/compact-client.ts",
-    "src/config.ts",
-    "src/debug.ts",
-    "src/details-store.ts",
-    "src/deferred-tool-carryover.ts",
-    "src/extension-runtime.ts",
-    "src/image-generation/artifacts.ts",
-    "src/image-generation/client.ts",
-    "src/image-generation/eligibility.ts",
-    "src/image-generation/extension.ts",
-    "src/image-generation/protocol.ts",
-    "src/image-generation/references.ts",
-    "src/image-generation/render.ts",
-    "src/image-generation/service.ts",
-    "src/image-generation/types.ts",
-    "src/auto-mode/extension.ts",
-    "src/auto-mode/policy.ts",
-    "src/auto-mode/prompt.ts",
-    "src/auto-mode/transcript.ts",
-    "src/auto-mode/reviewer.ts",
-    "src/auto-mode/classifier.ts",
-    "src/auto-mode/types.ts",
-    "extensions/codex-astra.ts",
-    "src/codex-astra/effort-planner.ts",
-    "src/codex-astra/extension.ts",
-    "src/model-scope.ts",
-    "src/native-fallback.ts",
-    "src/payload-rewrite.ts",
-    "src/provider-headers.ts",
-    "src/responses-headers.ts",
-    "src/remote-v2-client.ts",
-    "src/request-context-cache.ts",
-    "src/runtime.ts",
-    "src/serializer.ts",
-    "src/supported-environment.ts",
-    "src/types.ts",
-    "src/web-search/extension.ts",
-    "src/web-search/payload.ts",
-    "src/web-search/prompt.ts",
-    "src/web-search/types.ts",
-    "README.md",
-    "README_zh.md",
-    "LICENSE",
-    "NOTICE",
-    "tsconfig.check.json"
-  ],
-  "scripts": {
-    "test": "bun test",
-    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov && node ./scripts/check-lcov.mjs ./coverage/lcov.info",
-    "test:pi": "bun test ./test/pi-smoke.test.ts",
-    "typecheck": "tsc -p tsconfig.check.json"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.85.1",
-    "@earendil-works/pi-ai": ">=0.85.1",
-    "@earendil-works/pi-coding-agent": ">=0.85.1",
-    "@earendil-works/pi-tui": ">=0.85.1"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
-    "@types/node": "24.12.4",
-    "bun": "1.2.23",
-    "typescript": "5.9.3"
-  }
-}
+{
+  "name": "pi-openai-toolkit",
+  "version": "0.13.0",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction, native Web Search, native image generation, and model-reviewed auto mode.",
+  "author": "awoaCrim and contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awoaCrim/pi-openai-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/awoaCrim/pi-openai-toolkit/issues"
+  },
+  "homepage": "https://github.com/awoaCrim/pi-openai-toolkit#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "compaction",
+    "web-search",
+    "image-generation",
+    "auto-mode",
+    "codex",
+    "responses"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/compaction.ts",
+      "./extensions/web-search.ts",
+      "./extensions/image-generation.ts",
+      "./extensions/auto-mode.ts",
+      "./extensions/codex-astra.ts"
+    ]
+  },
+  "files": [
+    "extensions/compaction.ts",
+    "extensions/web-search.ts",
+    "extensions/image-generation.ts",
+    "extensions/auto-mode.ts",
+    "src/compact-client.ts",
+    "src/config.ts",
+    "src/debug.ts",
+    "src/details-store.ts",
+    "src/deferred-tool-carryover.ts",
+    "src/extension-runtime.ts",
+    "src/context-management/types.ts",
+    "src/context-management/messages.ts",
+    "src/context-management/window-budget.ts",
+    "src/context-management/window-request.ts",
+    "src/context-management/window-manager.ts",
+    "src/context-management/codex-provider.ts",
+    "src/context-management/history-notes.ts",
+    "src/context-management/tools.ts",
+    "src/context-management/namespace-tools.ts",
+    "src/context-management/tool-contract.ts",
+    "src/image-generation/artifacts.ts",
+    "src/image-generation/client.ts",
+    "src/image-generation/eligibility.ts",
+    "src/image-generation/extension.ts",
+    "src/image-generation/protocol.ts",
+    "src/image-generation/references.ts",
+    "src/image-generation/render.ts",
+    "src/image-generation/service.ts",
+    "src/image-generation/types.ts",
+    "src/auto-mode/extension.ts",
+    "src/auto-mode/policy.ts",
+    "src/auto-mode/prompt.ts",
+    "src/auto-mode/transcript.ts",
+    "src/auto-mode/reviewer.ts",
+    "src/auto-mode/classifier.ts",
+    "src/auto-mode/types.ts",
+    "extensions/codex-astra.ts",
+    "src/codex-astra/effort-planner.ts",
+    "src/codex-astra/extension.ts",
+    "src/model-scope.ts",
+    "src/native-fallback.ts",
+    "src/payload-rewrite.ts",
+    "src/provider-headers.ts",
+    "src/responses-headers.ts",
+    "src/remote-v2-client.ts",
+    "src/request-context-cache.ts",
+    "src/runtime.ts",
+    "src/serializer.ts",
+    "src/supported-environment.ts",
+    "src/types.ts",
+    "src/web-search/extension.ts",
+    "src/web-search/payload.ts",
+    "src/web-search/prompt.ts",
+    "src/web-search/types.ts",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    "NOTICE",
+    "tsconfig.check.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov && node ./scripts/check-lcov.mjs ./coverage/lcov.info",
+    "test:pi": "bun test ./test/pi-smoke.test.ts",
+    "typecheck": "tsc -p tsconfig.check.json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.85.1",
+    "@earendil-works/pi-ai": ">=0.85.1",
+    "@earendil-works/pi-coding-agent": ">=0.85.1",
+    "@earendil-works/pi-tui": ">=0.85.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@types/node": "24.12.4",
+    "bun": "1.2.23",
+    "typescript": "5.9.3"
+  }
+}

package/src/config.ts

@@ -30,6 +30,7 @@ import {
 	type AutoModeGate,
 	type CodexAstraConfig,
 	type CompactionConfig,
+	type ContextManagementMode,
 	type ImageGenerationConfig,
 	type LoadedToolkitConfig,
 	type NativeFallbackConfig,
@@ -43,10 +44,13 @@ export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration", "autoMode", "codexAstra"]);
 const COMPACTION_FIELDS = new Set([
 	"enabled",
+	"contextManagement",
+	"codexGatewayModels",
 	"allowCompactionContinuityBreak",
 	"remoteCompactModel",
 	"nativeFallback",
 	"responsesApis",
+	"contextReminderThresholdPercent",
 	"notifyOnLoad",
 	"debug",
 	"logProviderPayloads",
@@ -131,6 +135,20 @@ function toBoolean(value: unknown, fieldPath: string, warnings: string[]): boole
 	return undefined;
 }
 
+function toContextManagementMode(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): ContextManagementMode | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "string") {
+		const normalized = value.trim();
+		if (normalized === "off" || normalized === "remote") return normalized;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected one of off, remote.`);
+	return undefined;
+}
+
 function toModelSpec(value: unknown, fieldPath: string, warnings: string[]): string | null | undefined {
 	if (value === undefined) return undefined;
 	if (value === null) return null;
@@ -278,6 +296,17 @@ function applyCompactionConfig(
 	warnUnknownFields(raw, COMPACTION_FIELDS, "compaction", warnings);
 
 	resolved.enabled = toBoolean(raw.enabled, "compaction.enabled", warnings) ?? resolved.enabled;
+	resolved.contextManagement =
+		toContextManagementMode(raw.contextManagement, "compaction.contextManagement", warnings) ??
+		resolved.contextManagement;
+	const codexGatewayModels = toStringList(
+		raw.codexGatewayModels,
+		"compaction.codexGatewayModels",
+		warnings,
+	);
+	if (codexGatewayModels !== undefined) {
+		resolved.codexGatewayModels = codexGatewayModels;
+	}
 	resolved.allowCompactionContinuityBreak =
 		toBoolean(
 			raw.allowCompactionContinuityBreak,
@@ -286,6 +315,16 @@ function applyCompactionConfig(
 		) ?? resolved.allowCompactionContinuityBreak;
 	resolved.notifyOnLoad =
 		toBoolean(raw.notifyOnLoad, "compaction.notifyOnLoad", warnings) ?? resolved.notifyOnLoad;
+	const reminderPercent = toBoundedInteger(
+		raw.contextReminderThresholdPercent,
+		"compaction.contextReminderThresholdPercent",
+		warnings,
+		0,
+		100,
+	);
+	if (reminderPercent !== undefined) {
+		resolved.contextReminderThresholdPercent = reminderPercent;
+	}
 	resolved.debug = toBoolean(raw.debug, "compaction.debug", warnings) ?? resolved.debug;
 	resolved.logProviderPayloads =
 		toBoolean(raw.logProviderPayloads, "compaction.logProviderPayloads", warnings) ??