pi-openai-toolkit 0.22.3 → 0.23.1

package/README.md

@@ -52,11 +52,13 @@ Set `defaults.context.mode` or an individual model's `context.mode`:
 
 **Remote compaction** accepts `openai-responses`, `openai-codex-responses`, and `azure-openai-responses`. It tries V2 first. On the official OpenAI API-key route, a qualifying protocol failure can trigger one standalone `/v1/responses/compact` request; its complete encrypted replacement window is preserved for replay. OpenAI OAuth, native Codex, Azure, and gateways keep their existing V2 route. OpenAI subscription-sharing OAuth and native Codex login are separate grants, not interchangeable credentials. Backend/model access is still required.
 
-Set `context.remoteCompaction.model` to use a separate producer on the same effective base URL without changing the active model. Exhausted remote attempts warn before continuing with a native text summary. `nativeFallback.enabled: false` disables only Toolkit's configured-model tier, not Pi's default summary. Aborts, incompatible provenance, and edits to sealed history still cancel rather than bypassing checkpoint safety. See [context settings](docs/configuration.md#context) and [checkpoint rules](docs/internals.md#remote-compaction-v2-wire-contract).
+Set `context.remoteCompaction.model` to use a separate producer on the same effective base URL without changing the active model. For ordinary remote compaction, exhausted remote attempts warn before continuing with a native text summary. `nativeFallback.enabled: false` disables only Toolkit's configured-model tier, not Pi's default summary. Aborts, incompatible provenance, and edits to sealed history still cancel rather than bypassing checkpoint safety. See [context settings](docs/configuration.md#context) and [checkpoint rules](docs/internals.md#remote-compaction-v2-wire-contract).
 
 **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]` starts a checkpoint handoff: write notes successfully, then switch windows. 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.
+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.
+
+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.
 
 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

@@ -52,11 +52,13 @@ Toolkit 只读取一个全局配置文件，即使扩展安装在项目内也一
 
 **远程压缩**支持 `openai-responses`、`openai-codex-responses` 和 `azure-openai-responses`，先尝试 V2。官方 OpenAI API-key 路由遇到符合条件的协议失败时，可再尝试一次独立的 `/v1/responses/compact`，并完整保存返回的加密替换窗口用于重放。OpenAI OAuth、原生 Codex、Azure 和网关保持原有 V2 路由。OpenAI subscription-sharing OAuth 与原生 Codex 登录是两种独立授权，凭据不能互换；模型和后端仍须具备相应权限。
 
-可用 `context.remoteCompaction.model` 指定同一有效 base URL 下的独立压缩模型，不改变当前模型。远程尝试全部失败后，会明确提示并继续普通文本摘要。`nativeFallback.enabled: false` 只关闭 Toolkit 的指定模型回退层，不关闭 Pi 默认摘要。取消操作、来源不匹配或已封存历史被修改时，仍会取消，不能绕过检查点安全检查。详见[上下文配置](docs/configuration.md#context)和[检查点规则](docs/internals.md#remote-compaction-v2-wire-contract)。
+可用 `context.remoteCompaction.model` 指定同一有效 base URL 下的独立压缩模型，不改变当前模型。普通远程压缩的远程尝试全部失败后，会明确提示并继续文本摘要。`nativeFallback.enabled: false` 只关闭 Toolkit 的指定模型回退层，不关闭 Pi 默认摘要。取消操作、来源不匹配或已封存历史被修改时，仍会取消，不能绕过检查点安全检查。详见[上下文配置](docs/configuration.md#context)和[检查点规则](docs/internals.md#remote-compaction-v2-wire-contract)。
 
 **远程窗口**需要原生 `openai-codex` 提供商的 `openai-codex-responses` API，或支持相应协议的 `openai-responses` 网关。网关必须在精确模型下设置 `compatibility.transport: "codex-gateway"`；这一设置不会让普通兼容端点自动获得该能力。
 
-将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 会发起检查点交接：先成功写入 notes，再切换窗口。切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：只使用当前本地窗口，旧窗口历史不会发送给新模型或 compaction 模型。扩展会用一个不生成摘要的本地边界保留已持久化的 Remote Window / Context Session；切回支持窗口的模型时会复用同一个窗口，不会重复创建。该边界只写一次：之后在非窗口模型下的压缩会继续走普通 producer、native fallback 或 Pi 默认链路，而不再被取消。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
+将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 会远程压缩当前窗口，不切换当前模型，也不打开新窗口。检查点保存成功后由原模型继续；失败则停止并保留现有上下文，不回退到文本摘要。它沿用 `context.remoteCompaction.model` 设置；`null` 仍使用当前模型。
+
+切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：只使用当前本地窗口，旧窗口历史不会发送给新模型或 compaction 模型。扩展会用一个不生成摘要的本地边界保留已持久化的 Remote Window / Context Session；切回支持窗口的模型时会复用同一个窗口，不会重复创建。该边界只写一次：之后在非窗口模型下的压缩会继续走普通 producer、native fallback 或 Pi 默认链路，而不再被取消。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
 
 远程窗口依赖 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 producer reference; `null` uses the active model. In `remote-compaction`, it selects the synthetic checkpoint producer on the same effective base URL. In active `remote-windows`, manual `/compact` temporarily selects it for notes checkpoint duty on the same backend/account. |
-| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` preserves session/raw-branch input; `"pi-context-hook"` opts into Pi's ordered context projection. Checkpoint provenance must match. |
+| `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.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. |
@@ -73,11 +73,11 @@ Standalone success preserves the full canonical output window, including retaine
 
 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).
 
-In active `remote-windows`, `/compact [instructions]` starts checkpoint duty rather than producing a summary. The selected model must authenticate to the same native backend/account or gateway credential/affinity domain, fit the projected window plus its output reserve, and retain the required permitted context tools. Invalid or unsuitable explicit targets are refused without switching to a fallback model. The entire handoff uses the initiating context-policy snapshot; no config or global Pi defaults are rewritten.
+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.
 
-Only a new persisted successful notes write/append after the handoff and the latest delivered user message authorizes its rollover. After the exact target marker is durable, Toolkit restores the original model/thinking before new-window inference and asks it to read the receipt first. Failure or cancellation restores an owned selection; a later user selection takes priority. Failed restoration blocks further handoff requests until selection/auth is repaired. Reload can recover selection, but does not automatically restart inference.
+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.
 
-The SDK native compact call reports its intentional cancellation; the visible handoff is a separate agent operation. Pi's pre-hook “nothing to compact” and “already compacted” outcomes remain. Automatic threshold/overflow compaction and internal pending-trim maintenance do not initiate checkpoint duty. `nativeFallback.model` keeps its existing summary-model meaning.
+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.
 
 ---
 

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; a managed manual handoff retains its initiating context-policy snapshot until selection is restored. 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; 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.
 
 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.
 
@@ -117,23 +117,23 @@ State invariants the lifecycle code must keep honest:
 
 ### Managed manual compact
 
-[src/context-management/manual-compact.ts](../src/context-management/manual-compact.ts) owns manual checkpoint duty. It uses public Pi lifecycle and selection APIs; it does not replace the built-in command or patch the scheduler. [src/context-management/window-manager.ts](../src/context-management/window-manager.ts) remains the sole owner of notes pairing, window identity, projection and trim.
+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.
 
-1. An active managed `session_before_compact` with reason `manual` validates the source/target policies from one snapshot, actual permitted tools, remaining capacity and backend/account scope. It records the original model/thinking and cancels the native compact attempt. Internal window-bulk maintenance has a separate in-process owner even though Pi also labels it `manual`.
-2. The matching `session_compact_failed` callback launches duty only after Pi is idle. Public `setModel` changes the session selection, and a visible `sendUserMessage` rebuilds the target's normal prompt/tools. Delivery is observed through `message_start`; return from the fire-and-forget send API is not proof. A delivery timeout restores an abandoned idle selection.
-3. The existing `new_context` gate additionally requires a successful paired notes result after this operation and any later delivered user message. It records the exact target window before queueing a context-only marker, and returns a terminating result. Ordinary tools are blocked during checkpoint duty. Normal `new_context` outside this operation is unchanged.
-4. A terminating result alone does not stop mixed batches or queued messages. At `turn_end`, Toolkit requests abort without awaiting idle; context/request guards also refuse an unsafe continuation. The standard Responses and native Codex transports must not send an already-aborted continuation. Pi can deliver queued user content during that stop; it remains persisted and ordered for the original model.
-5. At `agent_settled`, after Pi has flushed custom messages, the controller verifies the exact durable marker and fresh checkpoint, restores original model/thinking, and sends one visible receipt-reading continuation. Pi 0.87 defers that continuation until every settled handler has returned, so later observers still see an idle session. Restoration finishes before the next provider request; marker `message_end` alone is not proof of persistence.
+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.
 
-Versioned `pi-openai-toolkit:manual-compact` custom entries record operation/session/branch/window identities, exact model keys, original thinking and phase. They contain no credentials, transcript copy or note contents. Reload/navigation reads the current branch and only recovers still-owned selection; it never retries notes, rollover or paid inference. A newer user model/thinking selection ends ownership. Failed restoration stays durable and blocks further provider requests until recovery or an explicit user selection.
+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.
 
-The underlying native compact promise still rejects its intentional cancellation. Empty/already-compacted sessions can fail before the extension hook. This is a separate handoff operation, not a fabricated successful native compaction. An observed user cancellation before the owned checkpoint stop restores selection without automatically resuming. Tests use the official Pi runtime, disk-backed sessions, isolated HOME/settings and synthetic Responses/native Codex traffic in [test/pi-managed-compact.test.ts](../test/pi-managed-compact.test.ts); they assert every request's model/thinking, marker/note order, retained tool head and queue preservation.
+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.
 
 ---
 
 ### Remote Compaction v2 wire contract
 
-v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway without an exact transport opt-in, can still compact through v2 when its API appears in `context.remoteCompaction.apis`. 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 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.
 
 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 +143,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, managed handoff and inactive Remote Context recovery retain their previous routing. 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, 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.
 
 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.22.3",
+  "version": "0.23.1",
   "private": false,
   "type": "module",
   "engines": {
@@ -69,6 +69,7 @@
     "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",