pi-openai-toolkit 0.23.0 → 0.23.2

package/README.md

@@ -56,9 +56,13 @@ Set `context.remoteCompaction.model` to use a separate producer on the same effe
 
 **Remote windows** require the native `openai-codex` provider with `openai-codex-responses`, or an `openai-responses` gateway implementing the protocol. Gateways require `compatibility.transport: "codex-gateway"` on the exact model entry. This setting does not add the capability to an ordinary compatible endpoint.
 
-Change `mode` in the example above to `remote-windows`. Eligible sessions expose `new_context`, `get_context_remaining`, `history`, and `notes`. Manual `/compact [instructions]` remotely compresses the current window without switching the active model or opening another window. After the checkpoint is saved, the original model continues; failure stops with the existing context preserved, without a text-summary fallback. It uses the same `context.remoteCompaction.model` setting; `null` keeps the current model.
+Change `mode` in the example above to `remote-windows`. Eligible sessions expose `new_context`, `get_context_remaining`, `history`, and `notes`. Manual `/compact [instructions]` uses Pi's native text compression of **only the current window**. It does not use the Toolkit remote producer or configured fallback, switch the active model, open another window, or send an automatic continuation. `remote-compaction` is the mode that selects Toolkit's remote/fallback compression chain.
 
-An existing effective window boundary survives model changes and switches to `remote-compaction` or `pi`: only the current local window is used, and retired Remote Context history is not sent to the model or a compaction producer. A no-summary local boundary preserves the persisted Remote Window / Context Session, so switching back to a supported model reuses the same window instead of opening a duplicate one. That boundary is written once: later compactions under a non-window model continue through the ordinary producer, native-fallback or Pi-default chain instead of being cancelled. The legacy `leaveManagedMode` setting is retained for config compatibility but no longer triggers bulk close-out compaction.
+An existing effective window boundary survives model changes and switches to `remote-compaction` or `pi`: retired history stays outside live requests and every compaction tier. Historical boundaries constrain input; they cannot replace a requested compression with no-summary cleanup. Window identity is preserved for switching back. An unsafe current-window view cancels rather than reopening archived windows. The legacy `leaveManagedMode` setting remains compatible but does not trigger bulk close-out compaction.
+
+Native text compression cannot read an existing encrypted checkpoint. If that checkpoint owns the current context, native compression/fallback cancels and preserves it instead of summarizing its placeholder and losing information. Compatible remote compression can still reuse it.
+
+Raw history remains in the local Pi session JSONL; remote `history`/`notes` are separate backend APIs. Window markers alone are not native Pi cutoffs, so request-time isolation requires the extension to be loaded. An old session already ending in a no-summary cleanup may report `Already compacted` before any extension hook; continue with a genuine user message before retrying. Toolkit does not rewrite those logs or bypass Pi's eligibility checks.
 
 Remote windows use alpha endpoints that may change upstream. When switching models, the remote window remains persisted and reusable; see the [window lifecycle](docs/internals.md#rollover-lifecycle).
 

package/README.zh.md

@@ -56,9 +56,13 @@ Toolkit 只读取一个全局配置文件，即使扩展安装在项目内也一
 
 **远程窗口**需要原生 `openai-codex` 提供商的 `openai-codex-responses` API，或支持相应协议的 `openai-responses` 网关。网关必须在精确模型下设置 `compatibility.transport: "codex-gateway"`；这一设置不会让普通兼容端点自动获得该能力。
 
-将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 会远程压缩当前窗口，不切换当前模型，也不打开新窗口。检查点保存成功后由原模型继续；失败则停止并保留现有上下文，不回退到文本摘要。它沿用 `context.remoteCompaction.model` 设置；`null` 仍使用当前模型。
+将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 使用 Pi 原生文本压缩，**只处理当前窗口**。它不调用 Toolkit 的远程 producer 或指定回退模型，不切换当前模型、打开新窗口，也不自动发送续跑提示。只有 `remote-compaction` 模式选择 Toolkit 的远程压缩及回退链路。
 
-切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：只使用当前本地窗口，旧窗口历史不会发送给新模型或 compaction 模型。扩展会用一个不生成摘要的本地边界保留已持久化的 Remote Window / Context Session；切回支持窗口的模型时会复用同一个窗口，不会重复创建。该边界只写一次：之后在非窗口模型下的压缩会继续走普通 producer、native fallback 或 Pi 默认链路，而不再被取消。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
+切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：旧历史不会进入普通请求或任何压缩层。历史边界只限定输入，不能把实际压缩替换成一次无摘要清理。窗口身份仍会保留，便于切回；无法安全重建当前窗口时取消操作，不退回全部归档历史。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
+
+原生文本压缩无法读取已有的加密检查点。如果当前上下文由该检查点承接，原生压缩或回退会取消并保留现状，避免把占位文本当作摘要、丢失信息；兼容的远程压缩仍可复用它。
+
+完整历史仍保存在本地 Pi 会话 JSONL，远端 `history`、`notes` 则是独立的后端 API。窗口标记本身不是 Pi 原生截断点，运行时隔离仍依赖扩展正常加载。旧会话若恰好以无摘要清理记录结尾，Pi 可能在进入扩展钩子前提示 `Already compacted`；先发送一条正常用户消息再重试。Toolkit 不改写原日志，也不绕过 Pi 的压缩资格检查。
 
 远程窗口依赖 alpha 接口，上游可能随时调整。切换模型时远程窗口状态仍会持久化并可复用，详见[窗口生命周期](docs/internals.md#rollover-lifecycle)。
 

package/docs/configuration.md

@@ -57,8 +57,8 @@ Place `context` under `defaults` or an exact `models` entry.
 | Relative field | Default | Contract |
 | --- | --- | --- |
 | `mode` | `"remote-compaction"` | `"pi"` delegates ordinary context management to Pi; `"remote-compaction"` uses the eligible Responses checkpoint path; `"remote-windows"` selects Codex windows where supported. |
-| `remoteCompaction.model` | `null` | Exact synthetic producer reference for `remote-compaction` and active `remote-windows` manual `/compact`, on the same effective base URL. `null` uses the active model; a separate producer never changes the active model. |
-| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` keeps the existing session/branch input path without request-time context hooks; `"pi-context-hook"` opts into Pi's ordered context projection. Active Remote manual compression uses the canonical effective current window in either mode. Checkpoint provenance must match. |
+| `remoteCompaction.model` | `null` | Exact synthetic producer reference for `remote-compaction`, on the same effective base URL. `null` uses the active model; a separate producer never changes the active model. `remote-windows` user `/compact` uses Pi native compression instead. |
+| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` uses canonical session input without request-time context hooks; `"pi-context-hook"` opts into Pi's ordered context projection. An inherited window restricts either source to its current context. Checkpoint provenance must match. |
 | `remoteCompaction.allowContinuityBreak` | `false` | Allow restarting from Pi context after a foreign compaction entry. It does not make malformed opaque checkpoints replayable. |
 | `remoteCompaction.apis` | `["openai-responses", "openai-codex-responses", "azure-openai-responses"]` | May narrow this set; `[]` permits no remote-compaction API. Azure uses Pi's resolved `AZURE_OPENAI_*` environment values for the `/openai/v1` Responses path, deployment mapping, and `api-version`; unsupported entries are errors. |
 | `nativeFallback.enabled` | `true` | Enable the existing native-method fallback tier. |
@@ -71,13 +71,21 @@ Ordinary remote compaction tries V2 first. One automatic standalone `/v1/respons
 
 Standalone success preserves the full canonical output window, including retained items, rather than treating retained assistant text as a summary. When actual remote attempts are exhausted, Toolkit warns that no encrypted checkpoint was produced and starts the existing native text-summary chain: the configured remote producer after a remote attempt, or `nativeFallback.model` when remote compaction is unavailable. `nativeFallback.enabled: false` disables only the configured-model tier; disabled/unset/same-model selections still permit Pi's default summary. Explicit summary-model failures and checkpoint-integrity failures cancel. OpenAI subscription-sharing OAuth can reject compaction; separately authenticating native Codex is a different route, not a way to reuse that grant. See the [wire contract](internals.md#remote-compaction-v2-wire-contract).
 
-Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. An existing effective Remote Window boundary survives model and context-mode changes, including `remote-compaction`, `pi`, and legacy disabled/off settings. A non-window consumer receives only the current local window; retired Remote Context history is excluded from live requests and compaction producers. This local safety check does not activate Remote tools or protocol support. A no-summary boundary preserves the marker for later reuse and is written once; later compaction under a non-window model continues through the ordinary producer/native/Pi-default chain. A configured window model whose activation fails does not silently receive a summary fallback. Normal `new_context` keeps its persisted-notes, duplicate and cooldown gates. Synthetic Remote V2 producer/consumer identity and checkpoint provenance are unchanged. See [Toolkit internals](internals.md).
+Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. An effective Remote Window boundary survives model and context-mode changes, including `remote-compaction`, `pi`, and legacy disabled/off settings. Retired history stays outside live requests and all compaction tiers without activating Remote tools for a non-window consumer. Historical boundaries constrain inputs; they do not choose a compression engine or replace requested compression with no-summary cleanup. Normal `new_context` retains its persisted-notes, duplicate and cooldown gates. See [Toolkit internals](internals.md).
 
-In active `remote-windows`, `/compact [instructions]` produces a Remote V2 encrypted checkpoint for only the effective current window. It excludes retired windows and checkpoints belonging to earlier boundaries, preserves the current prompt/tools and context edits, and uses the initiating policy snapshot. It does not select another active model, run a notes-writing agent, require a new notes checkpoint, or call `new_context`. The producer still needs the same effective base URL and supported runtime. Leaving `remoteCompaction.model` null does not move long-input compression to a cheaper model.
+The effective mode determines user `/compact [instructions]` policy:
 
-After the exact new checkpoint is persisted and Pi has finished manual compaction, the unchanged original model automatically continues in the same session/window. New user work, model/thinking selection, navigation or cancellation supersedes pending continuation; host queues are not cleared or reordered. If safe continuation cannot be established, the saved checkpoint remains available for manual resumption. Reload never restarts inference. Ordinary `notes`, `history` and `new_context` remain usable.
+- `remote-compaction`: Toolkit's ordinary Remote V2, eligible standalone, configured native and Pi-default chain. Manual, threshold and overflow compaction use this same policy, including immediately after leaving window mode.
+- `remote-windows`: Pi native text compression of **only the current window**. It does not invoke Toolkit's remote producer or configured fallback, write notes, switch models, call `new_context`, or send a post-compact continuation.
+- `pi`: native compression; any inherited effective window still limits the input to current context.
 
-Any failure in this active-manual path stops and preserves the existing context. It does not try standalone compaction, native text summary or Pi's active-model fallback, regardless of `nativeFallback.enabled`. Successful manual compact now returns a real compaction result; Pi's pre-hook “nothing to compact” and “already compacted” outcomes remain. Automatic threshold/overflow and internal pending-trim maintenance keep their existing behavior. Old persisted notes-handoff records remain readable for owned selection recovery only, without retrying inference. `nativeFallback.model` retains its existing meaning outside this active-manual scope.
+Input isolation is independent of engine selection. Native compression may run through a scoped public adapter when Pi's original preparation includes archived windows. Missing/edited ownership or an unsafe system/tool head cancels; whole archived history is not a repair source. Compaction results use real visible source IDs, preserve context edits and complete tool pairs, and leave raw session entries unchanged. Owned rollover trim remains a separate maintenance operation, not a successful user compression.
+
+Scoped native compression uses Pi's public `compact()` and bound model-registry transport, preserving auth, provider environment and current thinking. Host-private custom stream/retry callbacks are not available through this adapter; sessions without a window keep Pi's original default path. An encrypted current owner cannot be converted into a text summary: native/default/fallback cancels and preserves that checkpoint rather than summarizing its placeholder. Compatible remote recursion remains eligible.
+
+Manual success saves actual compressed output and waits for normal user continuation; Toolkit does not consume or reorder host queues. Pi still owns automatic scheduling and retry. Its pre-hook “nothing to compact” and “already compacted” checks remain: a legacy session already ending at no-summary cleanup needs a genuine new user message before another attempt. Old notes-handoff records remain readable only for owned selection recovery, without retrying inference.
+
+Local history remains in Pi's session JSONL; `history` and `notes` call separate backend APIs. Window markers alone are not native Pi cutoffs, so request-time filtering cannot guarantee isolation if the extension never loads. Existing native-recognized compaction boundaries remain effective without that filter; Toolkit does not split/delete raw logs or modify the host to create stronger unload guarantees.
 
 ---
 

package/docs/internals.md

@@ -21,7 +21,7 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). The README kee
 
 The single global document is loaded through [src/config.ts](../src/config.ts). [src/config/legacy.ts](../src/config/legacy.ts) owns unversioned compatibility; [src/config/v2.ts](../src/config/v2.ts) validates v2 scopes, resolves exact policy, and records leaf origins. [src/config/policy.ts](../src/config/policy.ts) defines effective values independently of persisted session data. See the [configuration reference](configuration.md) for supported fields and migration limits.
 
-Feature entrypoints resolve once per public operation and pass that immutable snapshot through awaited helpers. A separately named compaction producer is resolved from the same decoded document for its own identity. Subsequent independent callbacks reload; active Remote manual compression retains its initiating context-policy snapshot through the owned operation, while legacy handoffs retain theirs through owned selection recovery. There is no general cross-event provider transaction, project lookup, singleton cache, or config state writer. Internal legacy-shaped engine adapters preserve compaction/search algorithms without exposing v2 parsing to consumers. Cross-feature gateway policy belongs to the resolver, not the context enable switch.
+Feature entrypoints resolve once per public operation and pass that immutable snapshot through awaited helpers. A separately named compaction producer is resolved from the same decoded document for its own identity. Subsequent independent callbacks reload; a compression uses its initiating policy snapshot. Legacy recovery reads only its persisted owned selection record and never initiates a handoff. There is no general cross-event provider transaction, project lookup, singleton cache, or config state writer. Internal legacy-shaped engine adapters preserve compaction/search algorithms without exposing v2 parsing to consumers. Cross-feature gateway policy belongs to the resolver, not the context enable switch.
 
 Selected invalid policy blocks dependent operations; unrelated model errors remain reportable without replacing the selected model. Retired `autoMode` sections are ignored with a warning; they never create effective policy or invalidate other features. Image choices are checked before auth, uploads, or paid requests. The human `/toolkit-config` command inspects effective values, validation, or a migration candidate without action APIs or network access. Migration is preview-only; source bytes and unknown/dormant content stay untouched.
 
@@ -109,31 +109,34 @@ State invariants the lifecycle code must keep honest:
 - Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
 - Pi's canonical session projection is the source of effective history. Toolkit may further restrict that projection, but never reconstruct omitted or summarized messages from the raw branch. Boundary resolution uses projected source entries and the active branch's latest compaction; an older marker retained inside a newer compaction does not authorize dropping that compaction's summary.
 - Window identity and cleanup eligibility are separate. A persisted `codex-context-window` message restores identity after reload/fork, but its historical `trimPreviousWindow` flag is not an outstanding command. A newer native summary or opaque checkpoint supersedes old cleanup without erasing window identity. Missing or edited boundary evidence is never repaired by loading raw history.
-- Maintenance compaction and local-consumer detachment use the same effective-boundary rules. Only a safe current boundary can produce a no-summary compaction; obsolete cleanup must not move the retained start backwards or replace a newer summary/checkpoint. Preparation alone changes no durable state, and cancellation, retry and branch navigation are resolved from current evidence rather than callback acknowledgments. A boundary already consumed by its own no-summary compaction is not a dead end: the scheduled-trim path still refuses a second boundary, but a local consumer falls through to the ordinary compaction chain, because Pi's canonical projection already starts at that boundary and retired Remote history is outside every producer's input. User manual `/compact` still follows the managed handoff below.
-- An effective persisted window boundary belongs to the session, not the selected model or context mode. `context_with_system`, `before_provider_request`, and `session_before_compact` synchronize it before mode-specific exits, including `remote-compaction`, `pi`, and legacy disabled/off selections. A non-window consumer receives only the effective current context, with the current system/tool head preserved and internal markers removed; no Remote tools, metadata or affinity headers are activated by the local safety check. A pre-window opaque checkpoint cannot rehydrate retired history after local projection. When detachment is needed, the existing no-summary boundary runs before any configured, remote, native or Pi-default compaction producer. A boundary that a previous detach already persisted yields to that same producer chain instead of cancelling the operation. Once a later ordinary compaction owns effective context, the historical window does not suppress its summary or valid opaque replay. A genuinely new window can retire that checkpoint. Disabling opaque checkpoint generation through `responsesApis` does not disable required replay of an inherited checkpoint; an unsupported transport, authentication failure, or endpoint mismatch aborts the request instead of exposing its placeholder. The legacy `leaveManagedMode` setting remains compatible but does not start a bulk close-out from `model_select` or `agent_settled`.
-- Native text summarization delegates prompt construction, tool-result truncation, split-turn requests and output limits to Pi's `compact()`. Toolkit does not use character-count estimates to reject the configured summary model. If its resolution, authentication or summary generation fails, compaction is cancelled with the error and context is preserved; the active model is not an implicit retry target. Disabled/unset/same-model selections retain Pi's default path. Remote-window projection still excludes retired managed history before any producer call.
+- Genuine owned rollover maintenance may persist a safe no-summary boundary. It must not move the retained start backwards or replace a newer summary/checkpoint. User `/compact` and remote-compaction threshold/overflow do not treat that cleanup as successful compression: they prepare a strictly scoped current-window input and complete actual compression in the same host operation. Preparation alone changes no durable state.
+- An effective persisted window boundary belongs to the session, not the selected model or context mode. `context_with_system`, `before_provider_request`, and `session_before_compact` synchronize it before mode-specific exits, including `remote-compaction`, `pi`, and legacy disabled/off selections. A non-window consumer receives only the effective current context, with the current system/tool head preserved and internal markers removed; no Remote tools, metadata or affinity headers are activated by the local safety check. A pre-window opaque checkpoint cannot rehydrate retired history after local projection. A historical boundary limits the input of configured, remote, native and Pi-default compactors; it does not select an engine or cause an intermediate no-summary commit. Once a later ordinary compaction owns effective context, the historical window does not suppress its summary or valid opaque replay. A genuinely new window can retire that checkpoint. Disabling opaque checkpoint generation through `responsesApis` does not disable required replay of an inherited checkpoint; an unsupported transport, authentication failure, or endpoint mismatch aborts the request instead of exposing its placeholder. The legacy `leaveManagedMode` setting remains compatible but does not start a bulk close-out from `model_select` or `agent_settled`.
+- Native text summarization delegates prompt construction, tool-result truncation, split-turn requests and output limits to Pi's `compact()`. Toolkit does not use character-count estimates to reject the configured summary model. If its resolution, authentication or summary generation fails, compaction is cancelled with the error and context is preserved; the active model is not an implicit retry target. Disabled/unset/same-model selections retain native current-model policy. If the host preparation contains retired windows, a scoped adapter must produce the genuine native result instead of returning undefined with unsafe input. Remote-window projection excludes retired history before every producer call.
 
 ---
 
 ### Managed manual compact
 
-Active Remote Window manual `/compact` uses the shared Remote V2 client, not a notes-writing agent. [src/context-management/manual-compact.ts](../src/context-management/manual-compact.ts) owns its narrow cancellation/continuation lifecycle; [src/context-management/window-manager.ts](../src/context-management/window-manager.ts) remains the owner of window identity, canonical projection, notes pairing and trim. The built-in command and Pi scheduler are unchanged.
+There is no dedicated Remote Windows user `/compact` execution or post-idle continuation. The built-in command and Pi scheduler remain unchanged. Engine selection is independent of persisted window ownership:
 
-1. `session_before_compact` distinguishes user-manual requests from Toolkit-owned maintenance even though both have reason `manual`. Resolve the producer and original consumer from one policy snapshot without invoking model/thinking setters.
-2. Prepare only the canonical effective current window. A later window retires an older opaque checkpoint; a newer checkpoint supersedes historical window markers. Preserve the prompt/tool head, context edits, complete tool pairs, native encrypted notes/history output and current deferred schemas. Hook-source preparation runs the ordered context phases once without triggering a budget reminder or maintenance. Unsafe projection cancels instead of recovering raw history.
-3. Send one synthetic Remote V2 request, validate it and recheck operation ownership, then return a real compaction result for Pi to persist. Select a genuine retained start within the submitted window. Resolution, protocol, network, validation and cancellation failures stop with no standalone/text-summary fallback, notes duty or continuation.
-4. `session_compact` synchronizes and verifies the latest exact persisted checkpoint. Repeated checkpoints share a summary string, so an event entry ID or summary match alone is insufficient proof. The callback returns without awaiting idle or sending a prompt: Pi emits it before clearing manual-compaction state.
-5. A cancellable bounded deferred check uses public `ctx.isIdle()` and exact session/branch/window/checkpoint/selection evidence before one normal `sendUserMessage` continuation. New user work, selection, navigation, queued work, another compact or shutdown invalidates stale continuation. Host queues stay untouched. If safe continuation is unavailable, keep the successful checkpoint and stop without inference.
+1. Recognize explicitly owned rollover maintenance before user-manual routing, even though both can have reason `manual`.
+2. Only effective `context.mode=remote-compaction` chooses Toolkit's ordinary remote/fallback policy. `remote-windows` and `pi` select Pi native text compression, not the Toolkit producer or configured fallback.
+3. Build immutable current-window input from Pi's canonical projection whenever a window constrains context. Exclude retired plaintext, opaque checkpoints and file-operation metadata. Preserve the current prompt/tools, edits, complete tool pairs, owning checkpoint and real retained source IDs. Missing ownership or unsafe head repair cancels instead of reopening raw history.
+4. Remote compression uses the entire scoped window, including verified opaque replay and current tool declarations. Hook-source preparation executes both ordered phases once in a read-only async scope; legacy skips those hooks. Native compression rebuilds cut/split-prefix/previous-summary/file-operation preparation within the same scope. Merely filtering messages or cloning a hook event cannot make an unsafe host default preparation safe.
+5. Native execution uses public `compact()` with bound `ctx.modelRegistry.streamSimple`, model-specific auth/base URL/env and current thinking. The extension context does not expose host-private custom stream/retry callbacks; unscoped defaults remain host-owned. An existing opaque owner, even with malformed reserved details, cannot be merged by text summarization: cancel native/default/fallback and preserve it. A compatible remote compactor may still replay it; never resurrect its retired plaintext.
+6. Return actual compressed output to Pi for normal persistence. No intermediate cleanup commit, model switch, notes-writing duty, window rollover or synthetic continuation is part of user `/compact`. General cancellation and ownership checks remain required through consumption of the hook result; host queues stay untouched.
 
-Compression preserves the same session/window identity and does not call `new_context`. Ordinary notes/history and explicit rollover remain available; a later queued or persisted window must exclude the retired opaque checkpoint. The original working model consumes the checkpoint only after it is durable and manual compression is idle. Pi's pre-hook empty/already-compacted outcomes remain unchanged.
+Normal notes/history and explicit `new_context` are preserved. The raw session JSONL retains previous windows for audit; the backend history/notes APIs are separate storage. Request-time filtering is not a durable isolation guarantee when the extension never loads: Pi recognizes native compaction cutoffs, not Toolkit window markers by themselves.
 
-Old version-1 `pi-openai-toolkit:manual-compact` records remain decodable for owned selection recovery. Reload/navigation never retries their notes, rollover or inference; a newer user selection wins. New direct compression does not create notes-duty records or change the current model. Tests in [test/pi-managed-compact.test.ts](../test/pi-managed-compact.test.ts) use the official SDK, disk-backed sessions, isolated HOME/settings and mocked native/gateway traffic to verify input, persistence, continuation and failure ordering.
+Pi's pre-hook empty/already-compacted outcomes remain unchanged. A legacy session already ending at no-summary cleanup must receive a genuine new user entry before retrying. Toolkit does not fabricate entries, rewrite old logs or patch host eligibility. Old version-1 `pi-openai-toolkit:manual-compact` records remain decodable for owned selection recovery only; reload/navigation never retries notes, rollover or inference, and a newer user selection wins.
+
+The public SDK fixtures in [test/pi-compaction-policy.test.ts](../test/pi-compaction-policy.test.ts) verify actual producer/native input, disk persistence, manual no-continuation behavior and native threshold/overflow recovery with isolated HOME/settings and mocked native/gateway traffic.
 
 ---
 
 ### Remote Compaction v2 wire contract
 
-V2 serves ordinary eligible compaction and active Remote Window user-manual compaction. A model that Remote Context declines, such as a gateway without an exact transport opt-in, can still use the ordinary V2 path when its API appears in `context.remoteCompaction.apis`. Active Remote manual compression uses the stricter current-window and stop-on-failure contract above. Compaction generation follows the active strategy. Across mode changes, an already-persisted checkpoint remains authoritative until a safe newer window or compaction replaces it; a historical window identity alone must not suppress checkpoint replay.
+V2 serves eligible `remote-compaction` operations, including manual, threshold and overflow. A model that Remote Context declines, such as a gateway without an exact transport opt-in, can still use this path when its API appears in `context.remoteCompaction.apis`. `remote-windows` user-manual operations use native compression instead. An effective inherited window constrains input without changing that policy. Compaction generation follows the active strategy. Across mode changes, an already-persisted checkpoint remains authoritative until a safe newer window or compaction replaces it; a historical window identity alone must not suppress checkpoint replay.
 
 A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns, with no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact. The sentinel-only payload is never sent.
 
@@ -143,7 +146,7 @@ A missing, empty, or invalid V2 checkpoint is never stored. Ordinary compaction
 
 #### Official API-key standalone fallback
 
-The ordinary path reuses one resolved physical producer, auth snapshot, and prepared full input. After a qualifying V2 failure, it makes at most one POST to `https://api.openai.com/v1/responses/compact`. Eligibility requires `openai-responses`, no Codex gateway affinity, public `ModelRegistry.hasConfiguredAuth(model) === true` and `isUsingOAuth(model) === false`, and the final Authorization header matching the resolved Bearer key. Missing/throwing/nonboolean metadata is unknown, not API-key evidence. Provider aliases may qualify at the official endpoint; OAuth, native Codex, Azure, custom gateways, active Remote Window manual compression and inactive Remote Context recovery do not opt into this standalone fallback. No token-shape inspection, extra auth resolution, model/account switch, redirect, capability cache, or generated version/beta header is introduced.
+The ordinary path reuses one resolved physical producer, auth snapshot, and prepared full input. After a qualifying V2 failure, it makes at most one POST to `https://api.openai.com/v1/responses/compact`. Eligibility requires `openai-responses`, no Codex gateway affinity, public `ModelRegistry.hasConfiguredAuth(model) === true` and `isUsingOAuth(model) === false`, and the final Authorization header matching the resolved Bearer key. Missing/throwing/nonboolean metadata is unknown, not API-key evidence. Provider aliases may qualify at the official endpoint; OAuth, native Codex, Azure, custom gateways and inactive automatic Remote Context recovery do not opt into this standalone fallback. No token-shape inspection, extra auth resolution, model/account switch, redirect, capability cache, or generated version/beta header is introduced.
 
 Qualifying failures are HTTP 400/404/405/422/501 without auth/quota exclusions, invalid/empty successful V2 checkpoint responses, or streamed errors with a recognized unsupported-protocol code. HTTP 401/403/429, known subscription/auth/billing/rate-limit restrictions, network failures, aborts, and generic server outages never trigger another protocol probe. OpenAI subscription-sharing OAuth and native Codex OAuth are distinct grants; selecting a separately authenticated Codex route does not authorize copying its credential to OpenAI.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "private": false,
   "type": "module",
   "engines": {
@@ -64,11 +64,13 @@
     "src/context-management/window-request.ts",
     "src/context-management/window-bulk.ts",
     "src/context-management/window-manager.ts",
+    "src/context-management/scoped-compaction.ts",
     "src/context-management/manual-compact.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/responses-tools.ts",
     "src/context-management/tool-contract.ts",
     "src/image-generation/artifacts.ts",
     "src/image-generation/client.ts",