pi-openai-toolkit 0.15.1 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-openai-toolkit
 
-Add Codex context windows, Responses compaction, hosted tools, and reviewed tool calls to Pi.
+Add Codex context windows, Responses compaction, hosted tools, and tool-call review to Pi.
 
 [![npm version](https://img.shields.io/npm/v/pi-openai-toolkit.svg)](https://www.npmjs.com/package/pi-openai-toolkit)
 [![License: MIT](https://img.shields.io/npm/l/pi-openai-toolkit.svg)](LICENSE)
@@ -11,39 +11,37 @@ Add Codex context windows, Responses compaction, hosted tools, and reviewed tool
 
 | Feature | Use it to |
 | --- | --- |
-| Codex Remote Context | Use the adapted Codex window protocol to start a new context window and retrieve earlier windows with `history`. |
-| Remote Compaction v2 | Continue an eligible Responses session with an encrypted server checkpoint. |
-| Web Search routes | Choose local `pi-web-access`, hosted Responses `web_search`, or experimental CPA standalone `web_run` per exact model. |
-| Image generation | Call the hosted Responses image tool to generate images or edit explicitly supplied local references. |
-| Tool-call review | Use Toolkit's approval gate to ask a reviewer model whether selected tool calls may run. |
+| Codex Remote Context | Start new windows with the adapted Codex protocol and retrieve earlier work through `history`. |
+| Remote Compaction v2 | Continue Responses sessions with encrypted server checkpoints. |
+| Web Search | Choose local `pi-web-access`, Responses `web_search`, or experimental CPA `web_run` per model. |
+| Image generation | Generate or edit images with the hosted Responses image tool. |
+| Tool-call review | Have a reviewer model approve selected calls through Toolkit's approval gate. |
 
-The package uses Pi's existing model, authentication, and session configuration. It does not add a provider or model.
+The package uses Pi's existing models, authentication, and sessions. It does not add a provider or model.
 
 ## Install
 
-Requires Pi 0.85.1 or newer and Node.js 22.19.0 or newer.
+Requires Pi 0.87.0+ and Node.js 22.19.0+.
 
 ```bash
 pi install npm:pi-openai-toolkit
 ```
 
-Use `--local` to install the extension in the current project. Toolkit policy is still global; there are no project or environment policy overlays.
-
-Without a config file, Remote Compaction v2 is enabled for eligible models, Remote Context windows are off, search is unmanaged, image generation is disabled, and Auto Mode is unavailable. These defaults do not verify backend support.
-
-The only Toolkit config file is:
+Add `--local` for a project-local installation. Toolkit configuration is global in either case:
 
 `~/.pi/agent/extensions/pi-openai-toolkit/config.json`
 
-All JSON examples below except the Pi model-registration example use **configuration schema v2**. Create the file and parent directory if absent. Merge examples into an existing v2 document, keeping its other settings. An unversioned legacy file remains supported: do not add v2 fields to it or overwrite it with an example. First use `/toolkit-config migration-preview`; the [configuration reference](docs/configuration.md) explains the review and installed-version checks. Loading config and previewing migration never rewrite the source file.
+Create the file and parent directory if needed. Merge the Toolkit examples below into an existing **schema v2** config; do not replace unrelated settings. For an unversioned legacy config, run `/toolkit-config migration-preview` first. See the [migration guide](docs/configuration.md#legacy-compatibility-and-migration).
+
+By default, eligible models use Remote Compaction v2. Remote Context windows, image generation, and Auto Mode are off; search is unmanaged. Backend support is still required.
 
 ## Quick start: enable Remote Context
 
-This section is for Codex-style context windows. For search, images, or tool-call review only, skip to [Common tasks](#common-tasks).
+For search, images, or tool-call review only, skip to [Common tasks](#common-tasks).
 
 ### Use Pi's built-in Codex provider
 
-You must already be signed in to Pi's built-in `openai-codex` provider. Create or merge this v2 Toolkit config:
+Sign in to Pi's `openai-codex` provider, then add this Toolkit config:
 
 ```json
 {
@@ -54,19 +52,24 @@ You must already be signed in to Pi's built-in `openai-codex` provider. Create o
 }
 ```
 
-Start Pi with a model from your existing Codex catalog:
+Start Pi with a model ID from your Codex catalog:
 
 ```bash
 pi --model openai-codex/<model-id>
 ```
 
-Replace `<model-id>` with the ID shown by your Pi setup. The session is activated when `new_context`, `get_context_remaining`, `history`, and `notes` appear. This verifies activation, not a completed backend round trip.
+Look for `new_context`, `get_context_remaining`, `history`, and `notes`. Their presence confirms activation, not backend compatibility. Earlier windows stay accessible through `history` without being loaded into every request.
 
 ### Use a compatible gateway
 
-This route requires `openai-responses` and a gateway that preserves Remote Context's Codex protocol fields. A successful ordinary chat request does not prove Remote Context compatibility.
+The gateway must support `openai-responses` and the Codex Remote Context protocol. Ordinary chat support is not enough.
+
+If your model is already registered in `~/.pi/agent/models.json`, skip the registration example.
 
-If `~/.pi/agent/models.json` already registers a compatible model, skip registration and set Toolkit's exact model override below. Otherwise, add or merge this Pi provider entry. Replace the provider name, URL, environment variable, and model values with your setup. The numeric limits are examples, not project defaults.
+<details>
+<summary>Register a gateway model in Pi</summary>
+
+Merge this into Pi's models file. Replace the provider name, URL, key variable, model ID, and limits with your setup; the numbers are examples.
 
 ```json
 {
@@ -88,19 +91,23 @@ If `~/.pi/agent/models.json` already registers a compatible model, skip registra
 }
 ```
 
-Set the referenced key before starting Pi. In PowerShell:
+Set the key in PowerShell:
 
 ```powershell
 $env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
 ```
 
-In a POSIX shell:
+Or in a POSIX shell:
 
 ```bash
 export MY_GATEWAY_KEY="replace-with-your-gateway-key"
 ```
 
-Use the same terminal to start Pi. In the Toolkit config, make the key exactly match the registered provider and model ID:
+Start Pi from the same terminal.
+
+</details>
+
+Add the exact registered `provider/model-id` to Toolkit's config:
 
 ```json
 {
@@ -118,23 +125,23 @@ Use the same terminal to start Pi. In the Toolkit config, make the key exactly m
 pi --model my-gateway/gpt-5.6-luna
 ```
 
-Check for `new_context`, `get_context_remaining`, `history`, and `notes`. If absent, read the notification and check `/toolkit-config`, the exact model key, Pi API, credentials, and base URL. The transport setting opts into a protocol profile; it does not register a model or prove the backend supports it.
-
-Earlier windows remain retrievable through `history`, but are not all automatically inserted into the current context.
+Check for the same context tools listed above. If they are missing, use `/toolkit-config` and check the notification, model key, API, credentials, and URL.
 
 ## Common tasks
 
-### Continue a session with server-side compaction
+### Save work and switch windows with `/compact`
 
-Use `context.mode: "remote-compaction"` for the Responses compaction path (the default), or `"pi"` to relinquish Toolkit context management. Set `context.remoteCompaction.model` only when a separate model should produce the checkpoint. These fields belong under `defaults` or an exact `models` override.
+In an active Remote Context session, run `/compact` to save work to notes and enter a new window without a conversation summary. You can append instructions to the command.
 
-`context.remoteCompaction.inputSource` defaults to `"legacy"`: first compaction uses Pi's current session context, with event preparation as a last resort; recursion uses the raw branch tail. This preserves existing behavior but can diverge from provider-visible context when other extensions rewrite messages.
+To use a separate checkpoint model, set `context.remoteCompaction.model` under `defaults` or an exact model override. It must support Remote Context on the same backend/account; leaving it unset uses the current model. Toolkit restores your original model and thinking level before continuing. See [context settings and requirements](docs/configuration.md#context).
 
-Opt into `"pi-context-hook"` to use the ordered Pi context-hook projection. If that bridge is unavailable, compaction cancels rather than sending unprojected history. Checkpoints are source-specific; switching input sources requires a new checkpoint. See [protocol details](docs/internals.md#remote-compaction-v2-wire-contract).
+### Use server-side compaction
+
+Set `context.mode` to `"remote-compaction"` (the default) for encrypted Responses checkpoints, or `"pi"` to leave context management to Pi. Advanced input and fallback options are in the [configuration reference](docs/configuration.md#context).
 
 ### Choose a Web Search route
 
-Configure a global default and exact model overrides:
+Set a default route and override it for individual models:
 
 ```json
 {
@@ -150,16 +157,18 @@ Configure a global default and exact model overrides:
 }
 ```
 
-- `unmanaged` releases Toolkit ownership. It does not disable third-party search or all Internet access.
-- `local` preserves the original local `pi-web-access` tool state and removes conflicting hosted/standalone tools from provider payloads. It never activates a local tool that was inactive.
-- `hosted` replaces the local `web_search` function with the native Responses search tool and source annotations.
-- `standalone-alpha` deliberately opts into experimental CPA/Codex gateway search. It exposes sequential `web_run` and sends one isolated request per call to the provider-relative `/alpha/search`, using the current Pi model and credentials. The gateway must actually support that endpoint and capability; Toolkit does not probe or enable it.
+| Route | Behavior |
+| --- | --- |
+| `unmanaged` | Leave search to Pi and other extensions. |
+| `local` | Keep the existing local `pi-web-access` tools. |
+| `hosted` | Use Responses `web_search` with source annotations. |
+| `standalone-alpha` | Use experimental `web_run` on a CPA/Codex gateway that supports `/alpha/search`. |
 
-Exact overrides win over defaults. There are no patterns, inferred capabilities, or fallback between routes. Invalid selected policy blocks the affected operation instead of choosing another route. The legacy hosted model list remains readable, but its permissive failure behavior is not identical to explicit v2 `hosted`; migration preview flags that difference.
+Toolkit does not fall back between routes. See [search configuration](docs/configuration.md#web-search) for backend requirements.
 
 ### Generate an image
 
-Image generation requires a Responses session and may incur provider charges. Enable it globally:
+Requires a Responses session and may incur provider charges. Enable it with an image model your provider supports:
 
 ```json
 {
@@ -168,19 +177,17 @@ Image generation requires a Responses session and may incur provider charges. En
     "imageGeneration": {
       "enabled": true,
       "defaultModel": "gpt-image-2.5",
-      "allowedModels": ["gpt-image-2.5", "grok-imagine-image-2.0"]
+      "allowedModels": ["gpt-image-2.5"]
     }
   }
 }
 ```
 
-These are bare output-model IDs for the nested Responses `image_generation` tool. List order does not choose the default. `defaultModel` must belong to the nonempty `allowedModels` list; an optional one-call `model` must also be allowed. Invalid policy or a disallowed choice fails before authentication, reference upload, and paid dispatch. The provider must support the chosen model.
-
-`openai_generate_image` accepts text-to-image requests and edits using explicitly supplied local references. Image policy cannot be overridden per session model.
+Ask Pi to generate an image or edit explicitly supplied local references using `openai_generate_image`. The default model must be in `allowedModels`; image settings are global. See [image configuration](docs/configuration.md#images).
 
 ### Review tool calls automatically
 
-Make Auto Mode available to an exact model and choose its reviewer:
+Enable Auto Mode for a model and choose its reviewer:
 
 ```json
 {
@@ -196,38 +203,23 @@ Make Auto Mode available to an exact model and choose its reviewer:
 }
 ```
 
-`available` permits engagement; use `/auto on` or `--auto` to engage. `/auto off` explicitly disengages it. The default `side-effect` gate covers `bash`, `write`, `edit`, and configured extra tools; `gate: "all"` reviews every tool call. A reviewer timeout does not approve a call. Invalid configuration while engaged keeps a blocking gate until corrected or explicitly turned off.
-
-The TUI shows activation, review activity, and a footer status. Compatible Pi tool renderers also show per-call allowed, denied, blocked, or unreviewed states. If that renderer seam is unavailable, Toolkit warns once and retains the footer display. Reviewer, classifier, and circuit-breaker controls are in the [configuration reference](docs/configuration.md).
+Turn it on with `/auto on` or `--auto`, and off with `/auto off`. By default it reviews `bash`, `write`, `edit`, and configured extra tools; `gate: "all"` reviews every call. A reviewer timeout never approves a call. See [Auto Mode settings](docs/configuration.md#auto-mode).
 
 ## Common configuration
 
-The global file uses built-ins, then `defaults`, then exact `models["provider/model-id"]` overrides. Missing fields inherit; arrays replace; `false` and `0` are retained. Supported optional model references accept `null` to clear inheritance. Defaults are not master switches: an exact override can enable a feature whose default is disabled.
-
-| Field | Default | Use |
-| --- | --- | --- |
-| `defaults.context.mode` | `"remote-compaction"` | `"pi"`, `"remote-compaction"`, or `"remote-windows"`. |
-| `models[exact].compatibility.transport` | `"standard"` | Exact gateway opt-in with `"codex-gateway"`. |
-| `defaults.context.remoteCompaction.model` | `null` | Optional checkpoint producer. |
-| `defaults.context.remoteCompaction.inputSource` | `"legacy"` | Source-specific checkpoint input policy. |
-| `defaults.context.remoteWindows.reminderThresholdPercent` | `5` | `0` disables reminders and exhausted-window fallback. |
-| `defaults.webSearch.route` | `"unmanaged"` | Toolkit search ownership policy. |
-| `defaults.imageGeneration.enabled` | `false` | Global image-generation switch. |
-| `defaults.imageGeneration.defaultModel` | `"gpt-image-2.5"` | Explicit default output model. |
-| `defaults.imageGeneration.allowedModels` | `["gpt-image-2.5"]` | Allowed output models, global only. |
-| `defaults.autoMode.available` | `false` | Permission to engage tool review. |
-| `defaults.autoMode.gate` | `"side-effect"` | Selected side-effect tools or `"all"`. |
-| `defaults.autoMode.timeoutMs` | `30000` | Reviewer timeout in milliseconds. |
-| `diagnostics.level` | `"info"` | `"debug"` enables debug artifacts. |
-| `diagnostics.captureRequests` / `captureResponses` | `false` | Independent request/compact-response capture opt-ins. |
-
-Use `/toolkit-config` for effective values and origins, `/toolkit-config validate` for document issues, and `/toolkit-config migration-preview` for a read-only legacy candidate. These commands require a UI and perform no network/auth lookup, tool activation, or file writes. Configuration selection does not verify backend support.
-
-Unknown v2 policy keys and malformed values produce visible scoped errors, independent of debug mode. Each public callback or tool execution uses one immutable snapshot across its awaited helpers; later operations reread the file. Separate Pi events are not one atomic transaction. See the [complete configuration reference](docs/configuration.md) and [editor schema](config.schema.json).
+Use `defaults` for shared settings and `models["provider/model-id"]` for exact model overrides. Toolkit reads only the global config file.
+
+| Command | Purpose |
+| --- | --- |
+| `/toolkit-config` | Show effective settings and their origins. |
+| `/toolkit-config validate` | Check for configuration errors. |
+| `/toolkit-config migration-preview` | Preview a legacy-to-v2 migration without writing files. |
+
+These commands require Pi's interactive UI. See the [full configuration reference](docs/configuration.md), [editor schema](config.schema.json), and [implementation details](docs/internals.md).
 
 ## Development
 
-From the repository root, after dependencies are installed:
+After installing dependencies in the repository root:
 
 ```bash
 npm run typecheck

package/README.zh.md

@@ -11,39 +11,37 @@
 
 | 功能 | 用途 |
 | --- | --- |
-| Codex 远程上下文 | 使用适配的 Codex 窗口协议切换上下文窗口，并通过 `history` 检索较早窗口。 |
-| 远程压缩 v2 | 使用服务端返回的加密检查点继续符合条件的 Responses 会话。 |
-| 联网搜索路由 | 按精确模型选择本地 `pi-web-access`、Responses 托管 `web_search` 或实验性的 CPA 独立 `web_run`。 |
-| 图像生成 | 调用 Responses 托管生图工具生成图片，或编辑明确传入的本地参考图片。 |
-| 工具调用审查 | 使用 Toolkit 的审批门禁，由审查模型判断指定工具调用是否可以执行。 |
+| Codex 远程上下文 | 通过适配的 Codex 协议切换窗口，用 `history` 找回较早的工作内容。 |
+| 远程压缩 v2 | 使用加密的服务端检查点继续 Responses 会话。 |
+| 联网搜索 | 按模型选择本地 `pi-web-access`、Responses `web_search` 或实验性的 CPA `web_run`。 |
+| 图像生成 | 使用 Responses 托管生图工具生成或编辑图片。 |
+| 工具调用审查 | 通过 Toolkit 审批门禁，让审查模型判断指定调用是否可以执行。 |
 
-本包沿用 Pi 已有的模型、认证和会话配置，不新增提供商或模型。
+本包沿用 Pi 已有的模型、认证和会话，不新增提供商或模型。
 
 ## 安装
 
-需要 Pi 0.85.1 或更高版本，以及 Node.js 22.19.0 或更高版本。
+需要 Pi 0.87.0+ 和 Node.js 22.19.0+。
 
 ```bash
 pi install npm:pi-openai-toolkit
 ```
 
-在当前项目中安装扩展时加上 `--local`。Toolkit 策略仍然只使用全局配置，不支持项目配置或环境变量策略覆盖。
-
-没有配置文件时，符合条件的模型启用远程压缩 v2，远程上下文窗口关闭，搜索不由 Toolkit 管理，图像生成关闭，自动模式不可用。这些默认值不表示后端能力已经验证。
-
-Toolkit 唯一的配置文件是：
+加上 `--local` 可安装到当前项目。无论安装位置如何，Toolkit 都使用全局配置：
 
 `~/.pi/agent/extensions/pi-openai-toolkit/config.json`
 
-下文除 Pi 模型注册示例外，其他 JSON 示例均使用**配置格式 v2**。文件不存在时，创建文件及所需目录；已有 v2 配置时，将示例合并到对应对象并保留其他设置。无版本号的旧格式仍受支持，请勿直接加入 v2 字段，也不要用示例覆盖原文件。先运行 `/toolkit-config migration-preview`；[配置参考](docs/configuration.md)说明了审查和已安装版本检查要求。读取配置和预览迁移都不会改写源文件。
+文件不存在时，创建文件及所需目录。将下方 Toolkit 示例合并到已有的**配置格式 v2** 文件，不要覆盖其他设置。无版本号的旧配置请先运行 `/toolkit-config migration-preview`，详见[迁移指南](docs/configuration.md#legacy-compatibility-and-migration)。
+
+默认情况下，符合条件的模型启用远程压缩 v2；远程上下文窗口、生图和自动模式关闭，搜索不由 Toolkit 管理。使用相关功能仍需后端支持。
 
 ## 快速开始：启用远程上下文
 
-本节适用于想使用 Codex 风格上下文窗口的用户。如果只需要搜索、生图或工具调用审查，请跳到[常见用法](#常见用法)。
+如果只需要搜索、生图或工具调用审查，可跳到[常见用法](#常见用法)。
 
 ### 使用 Pi 内置的 Codex 提供商
 
-你需要先登录 Pi 内置的 `openai-codex` 提供商。创建或合并以下 v2 Toolkit 配置：
+先登录 Pi 的 `openai-codex` 提供商，再添加以下 Toolkit 配置：
 
 ```json
 {
@@ -54,19 +52,24 @@ Toolkit 唯一的配置文件是：
 }
 ```
 
-使用已有 Codex 模型目录中的模型启动 Pi：
+使用 Codex 模型目录中的实际模型 ID 启动 Pi：
 
 ```bash
 pi --model openai-codex/<model-id>
 ```
 
-将 `<model-id>` 换成 Pi 配置中实际显示的模型 ID。会话中出现 `new_context`、`get_context_remaining`、`history` 和 `notes`，说明已经激活；这不代表已完成后端往返验证。
+检查是否出现 `new_context`、`get_context_remaining`、`history` 和 `notes`。工具出现表示已激活，不代表后端兼容性已经验证。较早窗口可通过 `history` 检索，不会加载到每次请求中。
 
 ### 使用兼容网关
 
-本路线要求使用 `openai-responses`，并且网关保留远程上下文所需的 Codex 协议字段。普通对话请求成功，不代表远程上下文兼容性已经验证。
+网关必须支持 `openai-responses` 和 Codex 远程上下文协议，仅支持普通对话还不够。
+
+如果模型已在 `~/.pi/agent/models.json` 注册，可跳过注册示例。
 
-如果 `~/.pi/agent/models.json` 中已有兼容模型，可以跳过注册，直接设置下方 Toolkit 精确模型覆盖。否则，添加或合并下面的 Pi 提供商配置。请替换提供商名称、地址、环境变量和模型字段。示例数字不是项目默认值。
+<details>
+<summary>在 Pi 中注册网关模型</summary>
+
+将以下内容合并到 Pi 的模型文件。按实际情况替换提供商名称、URL、密钥变量、模型 ID 和限制值；其中的数字仅为示例。
 
 ```json
 {
@@ -88,19 +91,23 @@ pi --model openai-codex/<model-id>
 }
 ```
 
-启动 Pi 前设置配置中引用的密钥。PowerShell 使用：
+PowerShell 中设置密钥：
 
 ```powershell
 $env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
 ```
 
-POSIX shell 使用：
+或使用 POSIX shell：
 
 ```bash
 export MY_GATEWAY_KEY="replace-with-your-gateway-key"
 ```
 
-使用同一个终端启动 Pi。在 Toolkit 配置中，确保键与已注册的提供商名称和模型 ID 完全一致：
+在同一个终端中启动 Pi。
+
+</details>
+
+在 Toolkit 配置中填写已注册的精确 `提供商/模型 ID`：
 
 ```json
 {
@@ -118,23 +125,23 @@ export MY_GATEWAY_KEY="replace-with-your-gateway-key"
 pi --model my-gateway/gpt-5.6-luna
 ```
 
-检查是否出现 `new_context`、`get_context_remaining`、`history` 和 `notes`。如果没有，查看通知与 `/toolkit-config`，再检查精确模型键、Pi API、认证和基础 URL。传输设置只是显式选择协议适配，不会注册模型，也不能证明后端支持。
-
-较早窗口仍可通过 `history` 检索，但不会全部自动加入当前上下文。
+检查是否出现上面列出的上下文工具。如果没有，使用 `/toolkit-config`，并检查通知、模型键、API、认证和 URL。
 
 ## 常见用法
 
-### 使用服务端压缩继续会话
+### 用 `/compact` 保存工作并切换窗口
 
-使用 `context.mode: "remote-compaction"` 选择 Responses 压缩路径（默认值），或设为 `"pi"` 交回 Toolkit 的上下文管理权。只有需要独立模型生成检查点时才设置 `context.remoteCompaction.model`。这些字段放在 `defaults` 或精确的 `models` 覆盖下。
+远程上下文已激活时，运行 `/compact` 可将工作状态保存到 notes，再进入新窗口，不生成会话摘要。命令后可以附加要求。
 
-`context.remoteCompaction.inputSource` 默认为 `"legacy"`：首次压缩使用 Pi 当前会话上下文，最后才回退到事件提供的数据；递归压缩使用原始分支尾部。这保留了既有行为，但当其他扩展改写消息时，可能与提供商实际看到的上下文不同。
+如需独立的检查点模型，在 `defaults` 或精确模型覆盖下设置 `context.remoteCompaction.model`。目标模型须在同一后端及账号下支持远程上下文；不设置则使用当前模型。Toolkit 会在继续工作前恢复原模型和思考等级。详见[上下文配置与要求](docs/configuration.md#context)。
 
-主动选择 `"pi-context-hook"` 后，使用 Pi 有序上下文钩子投影。如果桥接不可用，压缩会取消，不会发送未投影的历史。检查点与来源绑定，切换来源后必须创建新检查点。详见[协议说明](docs/internals.md#remote-compaction-v2-wire-contract)。
+### 使用服务端压缩
+
+将 `context.mode` 设为 `"remote-compaction"`（默认值），使用加密的 Responses 检查点；设为 `"pi"` 则由 Pi 管理上下文。高级输入和回退选项见[配置参考](docs/configuration.md#context)。
 
 ### 选择联网搜索路由
 
-设置全局默认值和精确模型覆盖：
+设置默认路由，并按模型覆盖：
 
 ```json
 {
@@ -150,16 +157,18 @@ pi --model my-gateway/gpt-5.6-luna
 }
 ```
 
-- `unmanaged` 释放 Toolkit 的管理权，不会关闭第三方搜索或所有网络访问。
-- `local` 保留本地 `pi-web-access` 工具原先的激活状态，并从提供商请求中移除冲突的托管或独立搜索工具。原先未激活的本地工具不会被自动激活。
-- `hosted` 用原生 Responses 搜索工具和来源标注替换本地 `web_search` 函数。
-- `standalone-alpha` 显式启用实验性的 CPA/Codex 网关搜索。它暴露顺序执行的 `web_run`，每次调用向提供商相对路径 `/alpha/search` 发送一次隔离请求，使用当前 Pi 模型及认证。网关必须实际支持该端点和能力，Toolkit 不会探测或替你开启。
+| 路由 | 行为 |
+| --- | --- |
+| `unmanaged` | 由 Pi 和其他扩展管理搜索。 |
+| `local` | 保留现有本地 `pi-web-access` 工具。 |
+| `hosted` | 使用带来源标注的 Responses `web_search`。 |
+| `standalone-alpha` | 在支持 `/alpha/search` 的 CPA/Codex 网关上使用实验性的 `web_run`。 |
 
-精确覆盖优先于默认值。不支持模式匹配、猜测能力或路由间回退。选中策略无效时，会阻止受影响操作，不会改选其他路由。旧版托管模型列表仍可读取，但其宽松失败处理与 v2 显式 `hosted` 不完全相同；迁移预览会标出差异。
+Toolkit 不会在路由之间自动回退。后端要求见[搜索配置](docs/configuration.md#web-search)。
 
 ### 生成图片
 
-图像生成需要 Responses 会话，并且可能产生服务商费用。全局启用方式如下：
+需要 Responses 会话，并可能产生服务商费用。选择服务商支持的生图模型后启用：
 
 ```json
 {
@@ -168,19 +177,17 @@ pi --model my-gateway/gpt-5.6-luna
     "imageGeneration": {
       "enabled": true,
       "defaultModel": "gpt-image-2.5",
-      "allowedModels": ["gpt-image-2.5", "grok-imagine-image-2.0"]
+      "allowedModels": ["gpt-image-2.5"]
     }
   }
 }
 ```
 
-这里填写嵌套 Responses `image_generation` 工具使用的裸输出模型 ID。列表顺序不决定默认模型。`defaultModel` 必须属于非空的 `allowedModels` 列表，单次调用的可选 `model` 也必须在列表中。无效策略或不允许的选择会在认证、参考图上传及付费请求前被拒绝。提供商必须支持所选模型。
-
-`openai_generate_image` 支持文生图和使用明确传入的本地参考图进行编辑。生图策略不能按当前会话模型覆盖。
+让 Pi 通过 `openai_generate_image` 生成图片，或编辑明确提供的本地参考图。默认模型必须在 `allowedModels` 中；生图设置全局生效。详见[生图配置](docs/configuration.md#images)。
 
 ### 启用工具调用自动审查
 
-为精确模型开放自动模式，并选择审查模型：
+为模型开放自动模式，并选择审查模型：
 
 ```json
 {
@@ -196,34 +203,19 @@ pi --model my-gateway/gpt-5.6-luna
 }
 ```
 
-`available` 表示允许开启，使用 `/auto on` 或 `--auto` 才会实际开启；`/auto off` 明确关闭。默认 `side-effect` 范围覆盖 `bash`、`write`、`edit` 和额外配置的工具；`gate: "all"` 审查所有工具调用。审查超时不会自动放行。运行中配置变为无效时，已开启的门禁继续阻止调用，直到修正配置或明确关闭。
-
-TUI 会显示开启提示、审查活动和底部状态。兼容的 Pi 工具渲染器还会显示每次调用的允许、拒绝、阻止或未审查状态。如果渲染接口不可用，Toolkit 告警一次并保留底部显示。审查器、分类器和熔断器的高级配置见[配置参考](docs/configuration.md)。
+使用 `/auto on` 或 `--auto` 开启，`/auto off` 关闭。默认审查 `bash`、`write`、`edit` 和额外配置的工具；`gate: "all"` 审查所有调用。审查超时不会自动放行。详见[自动模式配置](docs/configuration.md#auto-mode)。
 
 ## 常用配置
 
-全局文件按内置值、`defaults`、精确 `models["provider/model-id"]` 的顺序解析。缺失字段继承，数组整体替换，`false` 和 `0` 保持含义。支持的可选模型引用可以用 `null` 清除继承。默认值不是总开关：精确覆盖可以开启默认关闭的功能。
-
-| 配置项 | 默认值 | 用途 |
-| --- | --- | --- |
-| `defaults.context.mode` | `"remote-compaction"` | `"pi"`、`"remote-compaction"` 或 `"remote-windows"`。 |
-| `models[exact].compatibility.transport` | `"standard"` | 用 `"codex-gateway"` 显式选择网关协议。 |
-| `defaults.context.remoteCompaction.model` | `null` | 可选的检查点生成模型。 |
-| `defaults.context.remoteCompaction.inputSource` | `"legacy"` | 与检查点来源绑定的输入策略。 |
-| `defaults.context.remoteWindows.reminderThresholdPercent` | `5` | `0` 关闭提醒和窗口耗尽兜底。 |
-| `defaults.webSearch.route` | `"unmanaged"` | Toolkit 搜索管理策略。 |
-| `defaults.imageGeneration.enabled` | `false` | 全局生图开关。 |
-| `defaults.imageGeneration.defaultModel` | `"gpt-image-2.5"` | 明确指定默认输出模型。 |
-| `defaults.imageGeneration.allowedModels` | `["gpt-image-2.5"]` | 允许的输出模型，仅支持全局设置。 |
-| `defaults.autoMode.available` | `false` | 是否允许开启工具审查。 |
-| `defaults.autoMode.gate` | `"side-effect"` | 指定副作用工具，或 `"all"`。 |
-| `defaults.autoMode.timeoutMs` | `30000` | 审查超时，单位为毫秒。 |
-| `diagnostics.level` | `"info"` | `"debug"` 开启调试产物。 |
-| `diagnostics.captureRequests` / `captureResponses` | `false` | 分别开启请求或压缩响应捕获。 |
-
-使用 `/toolkit-config` 查看有效值及来源，`/toolkit-config validate` 查看文档问题，`/toolkit-config migration-preview` 预览只读的旧格式迁移候选。这些命令需要 UI，不查询网络或认证，不激活工具，也不写文件。选中配置不表示后端支持已验证。
-
-未知 v2 策略键和畸形值会产生可见的分范围错误，不依赖调试模式。每个公开回调或工具执行及其等待的辅助操作使用同一份不可变快照，后续操作重新读取文件；独立 Pi 事件之间不保证原子事务。完整选项见[配置参考](docs/configuration.md)和[编辑器 schema](config.schema.json)。
+`defaults` 设置通用值，`models["provider/model-id"]` 按精确模型覆盖。Toolkit 只读取全局配置文件。
+
+| 命令 | 用途 |
+| --- | --- |
+| `/toolkit-config` | 查看生效设置及其来源。 |
+| `/toolkit-config validate` | 检查配置错误。 |
+| `/toolkit-config migration-preview` | 预览旧格式到 v2 的迁移，不写入文件。 |
+
+这些命令需要 Pi 交互界面。完整说明见[配置参考](docs/configuration.md)、[编辑器 schema](config.schema.json)和[实现细节](docs/internals.md)。
 
 ## 开发
 

package/docs/configuration.md

@@ -57,7 +57,7 @@ Place `context` under `defaults` or an exact `models` entry.
 | Relative field | Default | Contract |
 | --- | --- | --- |
 | `mode` | `"remote-compaction"` | `"pi"` relinquishes Toolkit context management; `"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. It must share the effective base URL required by the existing compaction path. |
+| `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.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"]` | May narrow this set; `[]` permits no remote-compaction API. Unsupported entries are errors. |
@@ -67,7 +67,13 @@ Place `context` under `defaults` or an exact `models` entry.
 | `remoteWindows.leaveManagedMode` | `"warn"` | `"compact"` also requests a close-out when retired history exceeds 80% of the next model's window and compaction can finish. Print mode remains warning-only; turn-end close-out requires a queued trim. |
 | `remoteWindows.reminderThresholdPercent` | `5` | Integer 0-100. `0` disables both the once-per-window reminder and exhausted-window fallback. |
 
-Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. `remote-windows` retains the compaction chain for models outside window capability. A configured window model whose activation fails does not silently receive a summary fallback. The rollover notes gate, durable history, producer/consumer identities, 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. `remote-windows` retains the compaction chain for models outside window capability. 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. If Auto Mode is engaged, the target must also be eligible for its gate. The entire handoff uses the initiating context-policy snapshot; no config or global Pi defaults are rewritten.
+
+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.
+
+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.
 
 ---
 
@@ -124,7 +130,7 @@ Place `autoMode` under `defaults` or an exact model. `available` permits engagem
 | `circuitBreaker.recentDenials` | `10` | Integer 0-100; `0` disables this limit. |
 | `circuitBreaker.windowSize` | `50` | Integer 1-200, recent-verdict window size. |
 
-Reviewer and classifier references are not active-session overrides. Classifier scores, denial history, and human decisions never become config entries.
+Reviewer and classifier references are not active-session overrides. Classifier scores, denial history, and human decisions never become config entries. The reviewer and its read-only evidence calls share one cancellable deadline, including dependencies that ignore abort. Denial history resets on actual delivery of a user message, including identical queued messages, not on enqueue or an ordinary tool continuation. Pre-scores are bound to a full structured authorization fingerprint; the bounded review transcript prioritizes recent user instructions and reports omissions.
 
 ---