pi-openai-toolkit 0.7.2 → 0.9.0

package/README.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>OpenAI-focused toolkit for <a href="https://github.com/earendil-works/pi">Pi</a>: Native Remote Compaction v2 & Hosted Web Search</strong>
+  <strong>OpenAI-focused toolkit for <a href="https://github.com/earendil-works/pi">Pi</a>: Remote Compaction v2, Hosted Web Search, Native Image Generation &amp; Model-Reviewed Auto Mode</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,12 @@
 
 ---
 
-`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles two high-performance extensions designed for OpenAI Responses endpoints:
+`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles four extensions designed for OpenAI Responses endpoints:
 
 1. **Remote Responses Compaction v2** (`extensions/compaction.ts`): Server-side opaque context compaction using the `remote_compaction_v2` SSE streaming protocol. Preserves context fidelity without lossy text re-summarization.
 2. **Model-Scoped Web Search** (`extensions/web-search.ts`): Toolkit-owned hosted Web Search for an exact `provider/model-id` allowlist configured with `webSearch.models`, across the supported `openai-responses` and `openai-codex-responses` APIs.
+3. **Native Image Generation** (`extensions/image-generation.ts`): A sequential local tool backed by the hosted Responses `image_generation` tool. It supports text-to-image and explicit local-reference edits while keeping binary image data out of session history.
+4. **Model-Reviewed Auto Mode** (`extensions/auto-mode.ts`): Pi does not prompt before running tools. Auto mode adds a gate on state-changing tool calls and lets a reviewer model you configure approve or deny each one, so the agent keeps working without interrupting you.
 
 ## Installation
 
@@ -57,6 +59,12 @@ pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/compaction.
 
 # Web Search only
 pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/web-search.ts
+
+# Image generation only
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/image-generation.ts
+
+# Auto mode only
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/auto-mode.ts
 ```
 
 > ⚠️ **Conflict Warning**: Do not run `pi-remote-compact`, `@lll9p/pi-better-compaction`, or standalone `pi-openai-web-search` alongside `pi-openai-toolkit`. Duplicate hooks cause race conditions and duplicated system prompts.
@@ -85,8 +93,11 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "enabled": true,
     "allowCompactionContinuityBreak": false,
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
-    "model": null,
-    "thinkingLevel": "off",
+    "nativeFallback": {
+      "enabled": true,
+      "model": null,
+      "thinkingLevel": "off"
+    },
     "autoCompaction": {
       "enabled": true,
       "continuation": "inline",
@@ -108,6 +119,21 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "imageGeneration": {
+    "enabled": false
+  },
+  "autoMode": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ],
+    "reviewerModel": "uwoacrimson/gpt-5.6-sol",
+    "gate": "side-effect",
+    "extraTools": [
+      "openai_generate_image"
+    ],
+    "timeoutMs": 30000
   }
 }
 ```
@@ -119,8 +145,9 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, default: `true`): Enable or disable Remote Compaction.
 - `allowCompactionContinuityBreak` (*boolean*, default: `false`): When `true`, allows restarting a fresh native opaque compaction chain from Pi's current session text if the latest compaction was made by another strategy (e.g. text summary).
 - `remoteCompactModel` (*string | null*, default: `null`): Model formatted as `provider/model-id` used only for the synthetic `remote_compaction_v2` request. Pi's active session model is not switched and resumes normal requests after compaction. The override must resolve to the same effective base URL as the active model; provider, Responses API identifier, and model may differ. `null` preserves the current same-model path.
-- `model` (*string | null*, default: `null`): Separate native text-summary fallback model formatted as `provider/model-id` (e.g. `"openai/gpt-4o-mini"`) used if remote v2 is unavailable or fails. If `null`, Pi uses its default current-model compaction path.
-- `thinkingLevel` (*string*, default: `"off"`): Reasoning / thinking level passed to Pi native compaction fallback (`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`).
+- `nativeFallback.enabled` (*boolean*, default: `true`): Master switch for toolkit-driven native compaction with an explicit summary model. It never touches the remote chain: `remote_compaction_v2` is still attempted and still wins when it succeeds. When `false`, only the post-failure native step is skipped, so every fallback falls straight through to Pi's own default compaction with the active model.
+- `nativeFallback.model` (*string | null*, default: `null`): Summary model formatted as `provider/model-id` (e.g. `"openai/gpt-4o-mini"`) used **only** when the active model cannot use remote v2 at all (non-Responses API, or an API excluded by `responsesApis`). It is never consulted once a remote request was attempted, and `null` means the active model runs Pi's default compaction path.
+- `nativeFallback.thinkingLevel` (*string*, default: `"off"`): Reasoning / thinking level passed to Pi's native `compact()` whenever this extension supplies the model (`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`).
 - `autoCompaction.enabled` (*boolean*, default: `true`): Check for compaction after a completed tool-result batch crosses Pi's context threshold.
 - `autoCompaction.continuation` (*`"inline" | "followUp" | "off"`*, default: `"inline"`): `inline` compacts inside the current official Pi 0.84.3 tool loop and refreshes the next provider context; `followUp` uses Pi's public hidden follow-up message path; `off` disables toolkit-triggered automatic compaction.
 - `autoCompaction.unsupportedFallback` (*`"followUp" | "off"`*, default: `"followUp"`): Behavior when the guarded official-host inline adapter is unavailable. It does not change normal remote/native compaction fallback ordering.
@@ -137,6 +164,25 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, default: `true`): Enable or disable native OpenAI Web Search injection.
 - `models` (*string[]*): Exact `provider/model-id` allowlist. Toolkit Web Search is used only for listed models running on `openai-responses` or `openai-codex-responses`. An empty list disables toolkit Web Search for all models.
 
+#### `imageGeneration`
+
+- `enabled` (*boolean*, default: `false`): The single opt-in switch for the `openai_generate_image` local tool. It defaults to off because every successful provider request may incur a charge.
+
+There is no model allowlist: the hosted `image_generation` tool is a capability of the Responses API, not of one vendor's model. Setting `enabled: true` exposes the tool to every active model whose API is `openai-responses` or `openai-codex-responses`, and hides it everywhere else. Web Search and compaction keep their own independent model allowlists.
+
+The request uses the current model's resolved Responses endpoint, authentication, and headers, while the hosted image tool itself is fixed to `gpt-image-2`; Pi does not switch the active conversation model. A gateway that does not support the hosted image tool still registers the tool and returns a bounded failure at call time; nothing is retried automatically.
+
+#### `autoMode`
+
+- `enabled` (*boolean*, default: `true`): Master switch. With `true` the mode can still never engage until you allowlist a model and set a reviewer.
+- `models` (*string[]*, default: `[]`): Exact `provider/model-id` allowlist of **active session models** permitted to run in auto mode. An empty list disables auto mode everywhere.
+- `reviewerModel` (*string | null*, default: `null`): The approving model, formatted as `provider/model-id`. It is resolved through Pi's model registry and must exist there; it is used only for one-off review requests and never becomes the active conversation model. Auto mode cannot engage while this is unset.
+- `gate` (*`"side-effect" | "all"`*, default: `"side-effect"`): `side-effect` reviews `bash`, `write`, and `edit`; `all` reviews every tool call, including read-only tools.
+- `extraTools` (*string[]*, default: `[]`): Additional tool names reviewed on top of the `side-effect` default set, for example `openai_generate_image` or an MCP tool name.
+- `timeoutMs` (*integer*, default: `30000`, range `1000`-`120000`): Reviewer deadline. Expiry never becomes approval.
+
+Auto mode is opt-in through the empty-by-default `models` allowlist because it authorizes a model to approve writes and shell commands on your behalf. Enable it for a session with `pi --auto` or `/auto on`, and use `/auto all` to review every tool at once. See [Core Mechanics](#core-mechanics) section 5 for the exact decision and fallback rules.
+
 ---
 
 ## Core Mechanics
@@ -166,8 +212,8 @@ Content-Type: application/json
 - **Fail-Closed Replay Guard**: Replay anchors on the Pi-authored compaction summary item by content and replaces it with the opaque compacted window; the post-compaction context is preserved verbatim, so transient messages injected by other extensions no longer block replay. If the summary anchor cannot be found, the toolkit aborts the provider request, shows an error notification, and always writes a content-free `*-replay-failure.json` artifact even when `logProviderPayloads` is disabled. The sentinel-only payload is never sent to the model.
 - **Graceful Multi-Tier Fallback**:
   1. Compatible Responses endpoints &rarr; Remote v2 Opaque Compaction.
-  2. Gateway failure or non-Responses model &rarr; Configured `compaction.model` fallback.
-  3. Otherwise &rarr; Pi default native text compaction.
+  2. Remote request attempted but failed on a model that *can* compact remotely &rarr; Pi's native `compact()` with `remoteCompactModel`, or the active model when no override is configured;
+  3. Model that cannot use remote v2 at all &rarr; Pi's native `compact()` with `compaction.nativeFallback.model`, or the active model when unset;
 
 ### 2. Tool-Loop Auto-Compaction and Continuation
 
@@ -188,6 +234,33 @@ For allowlisted models using `openai-responses` or `openai-codex-responses`, the
 - **Zero-Latency**: Uses Pi's existing connection, auth headers, and base URL without standalone HTTP overhead.
 - **Toolkit Ownership**: For an eligible model, the outgoing payload removes the local function tool named `web_search` so native search is the only search path. Switching to an ineligible model restores that local tool's previous active state.
 
+### 4. Native Image Generation and Editing
+
+When `imageGeneration.enabled` is `true` and the active model speaks a Responses API, Pi exposes the sequential `openai_generate_image` tool:
+
+- **Isolated request**: Sends one non-streaming, `store: false` Responses request containing only the image prompt and explicitly approved references. It does not forward recent conversation history and does not automatically retry after dispatch, avoiding accidental duplicate charges.
+- **Generation and editing**: Supports text-to-image or editing with 1-5 explicitly supplied local PNG, JPEG, or WebP reference paths. Reference upload always requires interactive confirmation; headless sessions reject reference uploads.
+- **Same route, fixed image model**: Reuses the current model's effective base URL, authentication, and provider headers, but requests the hosted `gpt-image-2` tool. It does not use a separate Codex OAuth flow or switch the active Pi model.
+- **PNG artifacts**: Validates the returned PNG and saves it under `<Pi agent dir>/generated-images/<session-id>/<image-call-id>.png`. Existing files are never overwritten.
+- **Safe optional copy**: A relative output path is allowed only in a trusted project. Paths outside both the trusted project and Pi agent directory require interactive confirmation. Output is PNG-only and existing destinations are rejected.
+- **Compact session data**: Tool results contain paths and bounded metadata, never image base64. The Pi TUI preview reads the canonical artifact from disk when image display is supported; deleting the artifact removes the preview. Explicit reference path strings remain part of the tool-call arguments, but reference bytes do not.
+- **Headless behavior**: Text-to-image with the default artifact path remains available without a UI. Reference uploads and external output paths that require approval are rejected in headless sessions.
+- **Billing and verification boundary**: The configured gateway/provider remains the billing authority; the tool does not synthesize Pi usage or cost metadata. Deterministic tests and smoke checks never dispatch image generation, and no live paid probe runs without separate explicit approval.
+
+### 5. Model-Reviewed Auto Mode
+
+Pi does not prompt before running `bash`, `write`, or `edit`; the only built-in trust prompt concerns project-local settings. This extension adds the approval gate and lets a reviewer model operate it, mirroring Codex's `approval_policy` plus `approvals_reviewer` pairing.
+
+- **Engagement is non-blocking**: `pi --auto`, `/auto on`, and `/auto all` only flip in-session state and update the footer status. No provider request happens at engagement time, so turning the mode on can never stall the current turn.
+- **Gate scope**: `side-effect` reviews `bash`, `write`, and `edit`; `extraTools` adds named tools; `/auto all` (or `gate: "all"`) reviews every tool call. Read-only tools pass through untouched in the default scope.
+- **One review per gated call**: The reviewer receives the tool name, its arguments, the most recent user request as intent, and the working directory. Tool arguments are labelled untrusted data, so text inside them cannot instruct the reviewer.
+- **Strict verdict contract**: The reviewer must answer with a single `{"decision":"allow"|"deny","reason":"..."}` object. Anything unparseable, an unknown decision, a provider error, a timeout, or a cancellation is reported as *unavailable* and never treated as approval.
+- **Deny feeds the agent**: A denial blocks the tool and returns the reviewer's reason to the requesting model, which can then choose a different approach instead of stalling.
+- **Human fallback**: When a review is unavailable in an interactive session, the extension asks you directly with the failure reason. In print (`-p`) and JSON mode there is nobody to ask, so the action fails closed and is blocked.
+- **Eligibility is rechecked live**: Switching to a model outside `autoMode.models`, clearing `reviewerModel`, or setting `enabled: false` disengages immediately. Returning to an allowlisted model does not re-engage automatically; you must ask again with `/auto on`.
+- **Bounded audit trail**: Every decision is persisted as a custom session entry (`pi-openai-toolkit.auto-mode-decision.v1`) containing the tool name, call id, decision, bounded reason, reviewer model, and decision source. Custom entries never enter LLM context, and tool arguments are not recorded.
+- **Cost boundary**: Each gated call adds one reviewer completion, so auto mode consumes model tokens. The reviewer runs with prompt caching disabled and no tools, and it cannot execute anything itself.
+
 ---
 
 ## Development & Testing

package/README_zh.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>专为 <a href="https://github.com/earendil-works/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2 & 原生托管联网搜索</strong>
+  <strong>专为 <a href="https://github.com/earendil-works/pi">Pi</a> 打造的 OpenAI 增强工具包：远端无损压缩 v2、原生托管联网搜索、图像生成与模型审批 Auto 模式</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,12 @@
 
 ---
 
-`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 全功能增强工具包，集成了两项针对 OpenAI Responses 协议的核心扩展：
+`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 增强工具包，集成了四项针对 OpenAI Responses 协议的扩展：
 
 1. **远端无损压缩 (Remote Compaction v2)** (`extensions/compaction.ts`): 基于 `remote_compaction_v2` SSE 流式协议实现的服务端密文无损会话压缩，彻底告别会话变长后丢失细节的文本二次摘要。
 2. **按模型启用的联网搜索** (`extensions/web-search.ts`): 通过 `webSearch.models` 精确匹配 `provider/model-id`，由 Toolkit 为符合条件的 `openai-responses` 与 `openai-codex-responses` 会话提供并拥有原生联网搜索。
+3. **原生图像生成** (`extensions/image-generation.ts`): 注册由 Responses 托管 `image_generation` 工具驱动的本地顺序工具，支持文生图和显式本地参考图编辑，同时避免把图像二进制写入会话历史。
+4. **模型审批 Auto 模式** (`extensions/auto-mode.ts`): Pi 默认不会为工具调用弹出审批确认。Auto 模式为改变状态的工具调用加上一道审批门，由你指定的审批模型判定放行或拦截，让 Agent 不必停下来等你确认也能继续推进。
 
 ## 安装使用
 
@@ -57,6 +59,12 @@ pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/compactio
 
 # 仅加载原生联网搜索
 pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/web-search.ts
+
+# 仅加载原生图像生成
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/image-generation.ts
+
+# 仅加载 Auto 模式
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/auto-mode.ts
 ```
 
 > ⚠️ **冲突提示**：请勿同时启用 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search`。多重钩子会产生竞态或注入重复的 System Prompt。
@@ -85,8 +93,11 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "enabled": true,
     "allowCompactionContinuityBreak": false,
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
-    "model": null,
-    "thinkingLevel": "off",
+    "nativeFallback": {
+      "enabled": true,
+      "model": null,
+      "thinkingLevel": "off"
+    },
     "autoCompaction": {
       "enabled": true,
       "continuation": "inline",
@@ -108,6 +119,21 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "imageGeneration": {
+    "enabled": false
+  },
+  "autoMode": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ],
+    "reviewerModel": "uwoacrimson/gpt-5.6-sol",
+    "gate": "side-effect",
+    "extraTools": [
+      "openai_generate_image"
+    ],
+    "timeoutMs": 30000
   }
 }
 ```
@@ -119,8 +145,9 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, 默认 `true`): 是否启用远端无损压缩。
 - `allowCompactionContinuityBreak` (*boolean*, 默认 `false`): 若最近一次历史压缩由其他方式（如文本摘要）生成，设为 `true` 允许直接从当前有效文本上下文重建密文压缩链。
 - `remoteCompactModel` (*string | null*, 默认 `null`): 仅用于 synthetic `remote_compaction_v2` 请求的模型，格式为 `"provider/model-id"`。Pi 不会切换当前会话模型，压缩完成后仍由原模型继续正常请求。覆盖模型必须与当前模型使用相同的实际生效 Base URL；Provider、Responses API 标识符和模型本身可以不同。为 `null` 时保持当前模型执行远端压缩的原有行为。
-- `model` (*string | null*, 默认 `null`): 独立的原生文本摘要降级模型，格式为 `"provider/model-id"`（例如 `"openai/gpt-4o-mini"`）。当 Remote v2 不可用或失败时使用；为 `null` 时进入 Pi 默认的当前模型压缩路径。
-- `thinkingLevel` (*string*, 默认 `"off"`): 降级模型调用 Pi 原生压缩时的思考级别（`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`）。
+- `nativeFallback.enabled` (*boolean*, 默认 `true`): Toolkit 用显式摘要模型跑原生压缩的总开关。它不影响远端链路：`remote_compaction_v2` 照常被尝试，成功时照常生效。设为 `false` 只跳过失败后的那一步原生压缩，因此所有降级都直接交给 Pi 默认的当前模型压缩。
+- `nativeFallback.model` (*string | null*, 默认 `null`): 摘要模型，格式为 `"provider/model-id"`（例如 `"openai/gpt-4o-mini"`），**仅**用于根本无法走远端 v2 的当前模型（非 Responses API，或 API 被 `responsesApis` 排除）。远端请求已经发出过的情境不会读这个字段；为 `null` 时由当前活动模型走 Pi 默认压缩路径。
+- `nativeFallback.thinkingLevel` (*string*, 默认 `"off"`): 由本扩展指定模型时，传给 Pi 原生 `compact()` 的思考级别。
 - `autoCompaction.enabled` (*boolean*, 默认 `true`): 完整工具调用/结果批次结束并越过 Pi 上下文阈值后，检查是否需要压缩。
 - `autoCompaction.continuation` (*`"inline" | "followUp" | "off"`*, 默认 `"inline"`): `inline` 在官方 Pi 0.84.3 当前工具循环内完成压缩并刷新下一次 Provider 上下文；`followUp` 使用 Pi 公共的隐藏后续消息；`off` 关闭 Toolkit 触发的自动压缩。
 - `autoCompaction.unsupportedFallback` (*`"followUp" | "off"`*, 默认 `"followUp"`): 官方 Host 私有 inline 适配器不可用时的处理方式，不改变原有远端/原生压缩降级顺序。
@@ -137,6 +164,25 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `enabled` (*boolean*, 默认 `true`): 是否启用原生 OpenAI 联网搜索注入。
 - `models` (*string[]*): 精确的 `provider/model-id` 模型白名单。只有列表中的模型在 `openai-responses` 或 `openai-codex-responses` 端点上运行时，才会使用 Toolkit Web Search。空列表表示所有模型都不启用 Toolkit Web Search。
 
+#### `imageGeneration`（图像生成配置）
+
+- `enabled` (*boolean*, 默认 `false`): 本地工具 `openai_generate_image` 的唯一开关。默认关闭是因为每一次成功的 Provider 请求都可能产生费用。
+
+这里没有模型白名单：托管 `image_generation` 是 Responses API 的能力，不属于某个厂商的特定模型。`enabled: true` 后，所有 API 为 `openai-responses` 或 `openai-codex-responses` 的当前模型都会拿到这个工具，其他 API 则完全看不到。联网搜索和压缩仍保留各自的模型白名单。
+
+请求复用当前模型解析后的 Responses 端点、认证和请求头，托管图像工具固定使用 `gpt-image-2`；Pi 不会切换当前会话模型。不支持托管图像工具的网关仍会注册该工具，并在调用时返回有界错误；发送后不会自动重试。
+
+#### `autoMode`（Auto 模式配置）
+
+- `enabled` (*boolean*, 默认 `true`): 总开关。即使为 `true`，在未配置模型白名单和审批模型之前，Auto 模式仍然无法启用。
+- `models` (*string[]*, 默认 `[]`): 允许以 Auto 模式运行的**当前会话模型**精确 `provider/model-id` 白名单。空列表表示任何模型都无法使用 Auto 模式。
+- `reviewerModel` (*string | null*, 默认 `null`): 执行审批的模型，格式为 `"provider/model-id"`。它通过 Pi 的模型注册表解析且必须存在，仅用于一次性审批请求，不会成为当前会话模型。未设置时 Auto 模式无法启用。
+- `gate` (*`"side-effect" | "all"`*, 默认 `"side-effect"`): `side-effect` 只审批 `bash`、`write`、`edit`；`all` 审批包括只读工具在内的全部工具调用。
+- `extraTools` (*string[]*, 默认 `[]`): 在 `side-effect` 默认集之上额外审批的工具名，例如 `openai_generate_image` 或某个 MCP 工具名。
+- `timeoutMs` (*整数*, 默认 `30000`，范围 `1000`–`120000`): 审批超时时间。超时永远不会被当作放行。
+
+Auto 模式需要显式启用（`models` 默认为空），因为它相当于允许一个模型代你批准文件写入和命令执行。会话内可用 `pi --auto` 或 `/auto on` 开启，`/auto all` 一次审批全部工具。具体判定与降级规则见「核心工作原理解析」第 5 节。
+
 ---
 
 ## 核心工作原理解析
@@ -166,8 +212,8 @@ Content-Type: application/json
 - **重放失败保护（Fail-Closed）**：重放以 Pi 生成的 compaction summary 哨兵为内容锚点，将其替换为密文压缩窗口；压缩后的其余上下文一律原样保留，因此其他扩展注入的临时消息不再阻断重放。若找不到哨兵锚点，插件会中止 provider 请求、弹出错误通知，并且即使 `logProviderPayloads` 关闭也会写入一份不含内容的安全失败记录 `*-replay-failure.json`。只含哨兵占位符的请求体永远不会发送给模型。
 - **三级优雅降级**：
   1. 支持的 Responses 端点 &rarr; 触发 Remote v2 密文无损压缩；
-  2. 网关不支持或报错 &rarr; 降级调用用户指定的 `compaction.model`；
-  3. 未配置降级模型 &rarr; 回退至 Pi 默认的当前模型摘要压缩。
+  2. 本可以远端压缩但网关报错或失败 &rarr; 用 `remoteCompactModel` 跑 Pi 原生 `compact()`，未配置覆盖模型则由当前活动模型执行；
+  3. 根本无法走远端的模型 &rarr; 用 `compaction.nativeFallback.model` 跑 Pi 原生 `compact()`，未配置则由当前活动模型执行；
 
 ### 2. 工具循环内自动压缩与续跑
 
@@ -188,6 +234,33 @@ Content-Type: application/json
 - **零额外网络延迟**：复用 Pi 当前活跃的 Provider 配置、认证凭据与 Base URL；
 - **Toolkit 接管搜索**：对于符合条件的模型，发给 Provider 的载荷会移除名为 `web_search` 的本地 Function Tool，只保留原生搜索；切换到不符合条件的模型后，会恢复该本地工具原先的 active 状态。
 
+### 4. 原生图像生成与编辑
+
+当 `imageGeneration.enabled` 为 `true` 且当前模型走 Responses API 时，Pi 会启用顺序工具 `openai_generate_image`：
+
+- **隔离请求**：仅发送一次非流式、`store: false` 的 Responses 请求，请求体只包含图像提示词和用户显式批准的参考图，不会附带最近会话历史；发送后不自动重试，避免重复计费。
+- **生成与编辑**：支持文生图，或使用 1–5 个显式指定的本地 PNG、JPEG、WebP 文件编辑。上传参考图前必须经过交互确认；Headless 会话拒绝上传参考图。
+- **复用当前路由，固定图像模型**：使用当前模型实际生效的 Base URL、认证和 Provider 请求头，但托管图像工具固定请求 `gpt-image-2`。不会走独立 Codex OAuth，也不会切换 Pi 当前模型。
+- **PNG Artifact**：校验返回的 PNG，并保存到 `<Pi agent dir>/generated-images/<session-id>/<image-call-id>.png`，绝不覆盖已有文件。
+- **安全的可选副本**：相对输出路径只允许写入可信项目；同时位于可信项目和 Pi Agent 目录之外的路径必须交互确认。仅支持 PNG，已有目标文件会被拒绝。
+- **紧凑会话数据**：工具结果只包含路径和有界元数据，不包含图像 Base64。终端支持图像显示时，Pi TUI 会从规范 Artifact 路径读取预览；删除 Artifact 后预览随即消失。显式参考路径字符串仍属于工具调用参数，但参考图字节不会写入会话。
+- **Headless 行为**：不带参考图并使用默认 Artifact 路径的文生图可在无 UI 环境运行；需要确认的参考图上传和外部输出路径会在 Headless 会话中被拒绝。
+- **计费与验证边界**：实际计费以配置的 Gateway/Provider 为准，工具不会自行构造 Pi usage/cost 元数据。确定性测试和冒烟检查不会发起生图请求；未经单独明确批准，也不会执行真实付费探针。
+
+### 5. 模型审批的 Auto 模式
+
+Pi 本身在运行 `bash`、`write`、`edit` 前不会询问确认，内置的唯一 trust 提示只针对项目本地配置。本扩展补上这道审批门，并让审批模型来操作它，对应 Codex 的 `approval_policy` 加 `approvals_reviewer` 组合。
+
+- **开启动作不阻塞任务流**：`pi --auto`、`/auto on`、`/auto all` 只切换会话内状态并更新底部状态栏，开启时不会发起任何 Provider 请求。
+- **审批范围**：`side-effect` 审批 `bash`、`write`、`edit`；`extraTools` 追加工具名；`/auto all`（或 `gate: "all"`）审批全部工具调用。默认范围下只读工具直接放行。
+- **每个受审调用一次审批**：审批模型收到工具名、完整参数、最近一次用户请求作为意图、以及工作目录。工具参数被标记为不可信数据，其中的文本无法反过来指挥审批模型。
+- **严格结论契约**：审批模型必须只回答一个 `{"decision":"allow"|"deny","reason":"..."}` 对象。无法解析、未知结论、Provider 报错、超时或取消都记为 *unavailable*，绝不视为放行。
+- **拒绝回喂主模型**：deny 会拦截该工具并把理由返回给发起调用的模型，让它改走其他方案而不是卡死。
+- **降级人工确认**：交互会话中审批不可用时，扩展会带着失败原因直接问你；而 `-p` 与 JSON 模式无人可问，因此 fail-closed 直接拦截。
+- **实时重新校验资格**：切到 `autoMode.models` 之外的模型、清空 `reviewerModel` 或设 `enabled: false` 会立即退出 Auto 模式；切回白名单模型不会自动恢复，必须重新 `/auto on`。
+- **有界审计记录**：每次判定都以自定义会话条目（`pi-openai-toolkit.auto-mode-decision.v1`）落盘，包含工具名、调用 id、结论、有界理由、审批模型和判定来源。自定义条目不进入 LLM 上下文，且不记录工具参数。
+- **费用边界**：每个受审调用额外产生一次审批补全，因此 Auto 模式会消耗模型 Token。审批请求禁用提示缓存、不携带任何工具，且自身无法执行操作。
+
 ---
 
 ## 测试与验证
@@ -201,6 +274,9 @@ bun test
 
 # Pi 冒烟测试
 npm run test:pi
+
+# 检查 npm 发布包内容
+npm pack --dry-run
 ```
 
 ---

package/extensions/auto-mode.ts

@@ -0,0 +1 @@
+export { default } from "../src/auto-mode/extension.ts";

package/extensions/image-generation.ts

@@ -0,0 +1 @@
+export { default } from "../src/image-generation/extension.ts";

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
-  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction and native Web Search.",
+  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction, native Web Search, native image generation, and model-reviewed auto mode.",
   "author": "awoaCrim and contributors",
   "license": "MIT",
   "repository": {
@@ -24,18 +24,24 @@
     "openai",
     "compaction",
     "web-search",
+    "image-generation",
+    "auto-mode",
     "codex",
     "responses"
   ],
   "pi": {
     "extensions": [
       "./extensions/compaction.ts",
-      "./extensions/web-search.ts"
+      "./extensions/web-search.ts",
+      "./extensions/image-generation.ts",
+      "./extensions/auto-mode.ts"
     ]
   },
   "files": [
     "extensions/compaction.ts",
     "extensions/web-search.ts",
+    "extensions/image-generation.ts",
+    "extensions/auto-mode.ts",
     "src/compact-client.ts",
     "src/config.ts",
     "src/debug.ts",
@@ -43,9 +49,24 @@
     "src/deferred-tool-carryover.ts",
     "src/inline-compaction.ts",
     "src/extension-runtime.ts",
+    "src/image-generation/artifacts.ts",
+    "src/image-generation/client.ts",
+    "src/image-generation/eligibility.ts",
+    "src/image-generation/extension.ts",
+    "src/image-generation/protocol.ts",
+    "src/image-generation/references.ts",
+    "src/image-generation/render.ts",
+    "src/image-generation/service.ts",
+    "src/image-generation/types.ts",
+    "src/auto-mode/extension.ts",
+    "src/auto-mode/policy.ts",
+    "src/auto-mode/reviewer.ts",
+    "src/auto-mode/types.ts",
+    "src/model-scope.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",
     "src/provider-headers.ts",
+    "src/responses-headers.ts",
     "src/remote-v2-client.ts",
     "src/request-context-cache.ts",
     "src/runtime.ts",
@@ -71,12 +92,14 @@
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": ">=0.80.0"
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@earendil-works/pi-tui": ">=0.80.0"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "0.84.3",
     "@earendil-works/pi-ai": "0.84.3",
     "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
     "@types/node": "24.12.4",
     "bun": "1.2.23",
     "typescript": "5.9.3"