pi-openai-toolkit 0.7.1 → 0.8.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</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,11 @@
 
 ---
 
-`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 three 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.
 
 ## Installation
 
@@ -57,6 +58,9 @@ 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
 ```
 
 > ⚠️ **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.
@@ -108,6 +112,12 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "imageGeneration": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ]
   }
 }
 ```
@@ -137,6 +147,13 @@ 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: `true`): Enable or disable the `openai_generate_image` local tool.
+- `models` (*string[]*, default: `[]`): Exact `provider/model-id` allowlist. The tool is active only for listed models using `openai-responses` or `openai-codex-responses`. The allowlist is independent from Web Search and compaction.
+
+Image generation remains opt-in through the empty-by-default `models` allowlist because each successful provider request may incur a charge. 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.
+
 ---
 
 ## Core Mechanics
@@ -163,7 +180,7 @@ Content-Type: application/json
 - **Validation Criteria**: Must return a valid SSE stream with `response.completed` (status `completed`) containing exactly one output item of `type: "compaction"` with non-empty `encrypted_content`.
 - **Remote Model Override**: `compaction.remoteCompactModel` can assign a same-gateway Responses model as the checkpoint producer while the active model remains the consumer. Its registered model metadata, authentication, headers, and effective base URL are used only for the synthetic compact request. Existing and recursive checkpoints remain replayable by the active model.
 - **Zero Loss Replay**: The opaque encrypted item is stored in `CompactionEntry.details.compactedWindow`. On subsequent requests, it is transparently prepended after fresh preamble instructions alongside live turns, eliminating lossy text re-summaries.
-- **Fail-Closed Replay Guard**: Replay verifies only the compaction summary sentinel plus the kept pre-compaction window derived from session entries; leading/trailing prompts and the post-compaction live tail are preserved verbatim, so transient messages injected by other extensions no longer block replay. If the kept region cannot be verified (e.g. `expected-pi-replay-mismatch` or `compaction-summary-not-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.
+- **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.
@@ -188,6 +205,19 @@ 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
+
+For an allowlisted Responses model, 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.
+
 ---
 
 ## 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、原生托管联网搜索与图像生成</strong>
 </p>
 
 <p align="center">
@@ -10,10 +10,11 @@
 
 ---
 
-`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` 工具驱动的本地顺序工具，支持文生图和显式本地参考图编辑，同时避免把图像二进制写入会话历史。
 
 ## 安装使用
 
@@ -57,6 +58,9 @@ 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
 ```
 
 > ⚠️ **冲突提示**：请勿同时启用 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search`。多重钩子会产生竞态或注入重复的 System Prompt。
@@ -108,6 +112,12 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "models": [
       "uwoacrimson/gpt-5.6-luna"
     ]
+  },
+  "imageGeneration": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ]
   }
 }
 ```
@@ -137,6 +147,13 @@ 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*, 默认 `true`): 是否启用本地工具 `openai_generate_image`。
+- `models` (*string[]*, 默认 `[]`): 精确的 `provider/model-id` 白名单。只有列表中的模型使用 `openai-responses` 或 `openai-codex-responses` 时才会激活工具；它与联网搜索、压缩配置相互独立。
+
+图像生成仍通过默认空白的 `models` 白名单显式启用，因为成功的 Provider 请求可能产生费用。请求复用当前模型解析后的 Responses 端点、认证和请求头，托管图像工具固定使用 `gpt-image-2`；Pi 不会切换当前会话模型。
+
 ---
 
 ## 核心工作原理解析
@@ -163,7 +180,7 @@ Content-Type: application/json
 - **校验标准**：接收 SSE 流并验证 `response.completed` 事件（状态为 `completed`），且返回且仅返回一个包含非空 `encrypted_content` 密文的 `type: "compaction"` 数据块。
 - **远端压缩模型覆盖**：`compaction.remoteCompactModel` 可以让同一网关上的另一个 Responses 模型负责生成 checkpoint，而当前活动模型仍是 checkpoint 的消费者。synthetic 压缩请求会使用覆盖模型在注册表中的模型元数据、认证、请求头和实际 Base URL；旧 checkpoint、递归压缩 checkpoint 都仍由当前活动模型重放。
 - **无损重放机制**：密文数据完整存入 `CompactionEntry.details.compactedWindow`。在后续对话中，插件会自动将密文插入在最新的系统指令之后与最新几轮消息之前，实现完全服务端无损上下文还原。
-- **重放失败保护（Fail-Closed）**：重放只校验 compaction summary 哨兵项以及由 session entries 推导出的压缩前保留窗口；前置/后置 prompt 与压缩后的实时尾部消息一律原样保留，因此其他扩展注入的临时消息不再阻断重放。若保留窗口无法与 session entries 对齐（如 `expected-pi-replay-mismatch`、`compaction-summary-not-found`），插件会中止 provider 请求、弹出错误通知，并且即使 `logProviderPayloads` 关闭也会写入一份不含内容的安全失败记录 `*-replay-failure.json`。只含哨兵占位符的请求体永远不会发送给模型。
+- **重放失败保护（Fail-Closed）**：重放以 Pi 生成的 compaction summary 哨兵为内容锚点，将其替换为密文压缩窗口；压缩后的其余上下文一律原样保留，因此其他扩展注入的临时消息不再阻断重放。若找不到哨兵锚点，插件会中止 provider 请求、弹出错误通知，并且即使 `logProviderPayloads` 关闭也会写入一份不含内容的安全失败记录 `*-replay-failure.json`。只含哨兵占位符的请求体永远不会发送给模型。
 - **三级优雅降级**：
   1. 支持的 Responses 端点 &rarr; 触发 Remote v2 密文无损压缩；
   2. 网关不支持或报错 &rarr; 降级调用用户指定的 `compaction.model`；
@@ -188,6 +205,19 @@ Content-Type: application/json
 - **零额外网络延迟**：复用 Pi 当前活跃的 Provider 配置、认证凭据与 Base URL；
 - **Toolkit 接管搜索**：对于符合条件的模型，发给 Provider 的载荷会移除名为 `web_search` 的本地 Function Tool，只保留原生搜索；切换到不符合条件的模型后，会恢复该本地工具原先的 active 状态。
 
+### 4. 原生图像生成与编辑
+
+当当前 Responses 模型在白名单中时，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 元数据。确定性测试和冒烟检查不会发起生图请求；未经单独明确批准，也不会执行真实付费探针。
+
 ---
 
 ## 测试与验证
@@ -201,6 +231,9 @@ bun test
 
 # Pi 冒烟测试
 npm run test:pi
+
+# 检查 npm 发布包内容
+npm pack --dry-run
 ```
 
 ---

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.1",
+  "version": "0.8.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, and native image generation.",
   "author": "awoaCrim and contributors",
   "license": "MIT",
   "repository": {
@@ -24,18 +24,21 @@
     "openai",
     "compaction",
     "web-search",
+    "image-generation",
     "codex",
     "responses"
   ],
   "pi": {
     "extensions": [
       "./extensions/compaction.ts",
-      "./extensions/web-search.ts"
+      "./extensions/web-search.ts",
+      "./extensions/image-generation.ts"
     ]
   },
   "files": [
     "extensions/compaction.ts",
     "extensions/web-search.ts",
+    "extensions/image-generation.ts",
     "src/compact-client.ts",
     "src/config.ts",
     "src/debug.ts",
@@ -43,9 +46,20 @@
     "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/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 +85,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"

package/src/compact-client.ts

@@ -1,5 +1,5 @@
 import { writeDebugArtifact } from "./debug";
-import { mergeProviderHeaders } from "./provider-headers";
+import { buildResponsesRequestHeaders } from "./responses-headers";
 import type { NativeCompactionRuntime } from "./runtime";
 import type { NativeCompactionRequestBody } from "./serializer";
 import type { ArtifactContext, CompactionConfig } from "./types";
@@ -112,57 +112,10 @@ export function extractCompactedSummaryText(output: readonly unknown[]): string
 	return joined.length > 0 ? joined : undefined;
 }
 
-function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
-	const parts = token.split(".");
-	if (parts.length !== 3) {
-		return undefined;
-	}
-
-	try {
-		const payloadText = Buffer.from(parts[1]!, "base64url").toString("utf8");
-		const payload = JSON.parse(payloadText);
-		return isRecord(payload) ? payload : undefined;
-	} catch {
-		return undefined;
-	}
-}
-
-function extractCodexAccountId(token: string): string | undefined {
-	const payload = decodeJwtPayload(token);
-	const authClaims = payload?.["https://api.openai.com/auth"];
-	if (!isRecord(authClaims)) {
-		return undefined;
-	}
-
-	const accountId = authClaims.chatgpt_account_id;
-	return typeof accountId === "string" && accountId.trim().length > 0 ? accountId.trim() : undefined;
-}
-
-function buildCodexUserAgent(): string {
-	const platform = typeof process !== "undefined" ? process.platform : "browser";
-	const arch = typeof process !== "undefined" ? process.arch : "unknown";
-	return `pi (${platform}; ${arch})`;
-}
-
 function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
-	const headers = new Headers(mergeProviderHeaders(runtime.currentModel.headers, runtime.headers));
-	headers.set("accept", JSON_CONTENT_TYPE);
-	headers.set("content-type", JSON_CONTENT_TYPE);
-	if (!headers.has("authorization")) {
-		headers.set("authorization", `Bearer ${runtime.apiKey}`);
-	}
-
-	if (runtime.api === "openai-codex-responses") {
-		const accountId = extractCodexAccountId(runtime.apiKey);
-		if (accountId) {
-			headers.set("chatgpt-account-id", accountId);
-		}
-		headers.set("originator", "pi");
-		headers.set("user-agent", buildCodexUserAgent());
-		headers.set("openai-beta", "responses=experimental");
-	}
-
-	return Object.fromEntries(headers.entries());
+	return Object.fromEntries(
+		buildResponsesRequestHeaders(runtime, { accept: JSON_CONTENT_TYPE }).entries(),
+	);
 }
 
 function writeCompactArtifact(

package/src/config.ts

@@ -6,11 +6,13 @@ import {
 	DEFAULT_COMPACTION_CONFIG,
 	DEFAULT_TOOLKIT_CONFIG,
 	DEFAULT_AUTO_COMPACTION_CONFIG,
+	DEFAULT_IMAGE_GENERATION_CONFIG,
 	DEFAULT_WEB_SEARCH_CONFIG,
 	RESPONSES_COMPACT_CAPABLE_APIS,
 	THINKING_LEVELS,
 	TOOLKIT_ID,
 	type CompactionConfig,
+	type ImageGenerationConfig,
 	type LoadedToolkitConfig,
 	type ToolkitConfig,
 	type WebSearchConfig,
@@ -19,7 +21,7 @@ import {
 export const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", TOOLKIT_ID);
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
-const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch"]);
+const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration"]);
 const COMPACTION_FIELDS = new Set([
 	"enabled",
 	"allowCompactionContinuityBreak",
@@ -37,6 +39,7 @@ const COMPACTION_FIELDS = new Set([
 ]);
 const AUTO_COMPACTION_FIELDS = new Set(["enabled", "continuation", "unsupportedFallback", "reserveTokens"]);
 const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
+const IMAGE_GENERATION_FIELDS = new Set(["enabled", "models"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -193,6 +196,10 @@ function cloneDefaults(): ToolkitConfig {
 			...DEFAULT_WEB_SEARCH_CONFIG,
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
 		},
+		imageGeneration: {
+			...DEFAULT_IMAGE_GENERATION_CONFIG,
+			models: [...DEFAULT_IMAGE_GENERATION_CONFIG.models],
+		},
 	};
 }
 
@@ -305,6 +312,21 @@ function applyWebSearchConfig(
 	}
 }
 
+function applyImageGenerationConfig(
+	raw: Record<string, unknown>,
+	resolved: ImageGenerationConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, IMAGE_GENERATION_FIELDS, "imageGeneration", warnings);
+	resolved.enabled =
+		toBoolean(raw.enabled, "imageGeneration.enabled", warnings) ?? resolved.enabled;
+
+	const models = toModelAllowlist(raw.models, "imageGeneration.models", warnings);
+	if (models !== undefined) {
+		resolved.models = models;
+	}
+}
+
 /**
  * Load the canonical toolkit config from
  * `~/.pi/agent/extensions/pi-openai-toolkit/config.json`.
@@ -335,6 +357,14 @@ export function loadToolkitConfig(configPath: string = CONFIG_PATH): LoadedToolk
 				warnings.push("Ignoring webSearch: expected a JSON object.");
 			}
 		}
+
+		if (raw.imageGeneration !== undefined) {
+			if (isRecord(raw.imageGeneration)) {
+				applyImageGenerationConfig(raw.imageGeneration, resolved.imageGeneration, warnings);
+			} else {
+				warnings.push("Ignoring imageGeneration: expected a JSON object.");
+			}
+		}
 	}
 
 	resolved.compaction.artifactRoot = resolveConfiguredPath(

package/src/extension-runtime.ts

@@ -548,12 +548,10 @@ async function handleBeforeProviderRequest(event: BeforeProviderRequestEvent, ct
 			firstKeptEntryIndex: rewrite.segments.firstKeptEntryIndex,
 			originalInputItems: payload.input.length,
 			rewrittenInputItems: rewrite.rewrittenPayload.input.length,
-			freshPreambleItems: rewrite.segments.freshPreamble.length,
-			trailingPreambleItems: rewrite.segments.trailingPreamble.length,
+			leadingItems: rewrite.segments.leading.length,
 			compactionSummaryItems: rewrite.segments.compactionSummary.length,
-			preCompactionKeptItems: rewrite.segments.preCompactionKeptWindow.input.length,
 			compactedItems: rewrite.segments.compactedWindow.length,
-			postCompactionTailItems: rewrite.segments.postCompactionTail.input.length,
+			postItems: rewrite.segments.post.length,
 			payload: rewrite.rewrittenPayload,
 			originalPayload: payload,
 		},

package/src/image-generation/artifacts.ts

@@ -0,0 +1,237 @@
+import { constants as fsConstants } from "node:fs";
+import {
+	link,
+	mkdir,
+	open,
+	realpath,
+	stat,
+	unlink,
+} from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import {
+	basename,
+	dirname,
+	extname,
+	isAbsolute,
+	join,
+	relative,
+	resolve,
+	sep,
+} from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	MAX_IMAGE_PATH_CHARS,
+	ImageGenerationError,
+	sanitizeImageDiagnostic,
+} from "./types";
+
+export type ExplicitOutputPlan = {
+	path: string;
+};
+
+function isPathInsideOrEqual(root: string, candidate: string): boolean {
+	const rel = relative(root, candidate);
+	return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+function sanitizePathPart(value: string, fallback: string): string {
+	const sanitized = value
+		.trim()
+		.replace(/[^A-Za-z0-9._-]+/g, "-")
+		.replace(/^[.-]+|[.-]+$/g, "")
+		.slice(0, 120);
+	return sanitized || fallback;
+}
+
+async function realDirectory(path: string): Promise<string> {
+	return realpath(path).catch(() => resolve(path));
+}
+
+async function resolveWriteTarget(candidate: string): Promise<string> {
+	const suffix: string[] = [];
+	let current = resolve(candidate);
+	while (true) {
+		try {
+			const info = await stat(current);
+			if (suffix.length > 0 && !info.isDirectory()) {
+				throw new ImageGenerationError(
+					"output-path-invalid",
+					`Output parent is not a directory: ${current}`,
+				);
+			}
+			const existing = await realpath(current);
+			return resolve(existing, ...suffix);
+		} catch (error) {
+			if (error instanceof ImageGenerationError) throw error;
+			if (
+				error &&
+				typeof error === "object" &&
+				"code" in error &&
+				error.code !== "ENOENT"
+			) {
+				throw new ImageGenerationError(
+					"output-path-invalid",
+					`Unable to inspect output path: ${candidate}`,
+				);
+			}
+			const parent = dirname(current);
+			if (parent === current) {
+				throw new ImageGenerationError(
+					"output-path-invalid",
+					`Unable to resolve output path: ${candidate}`,
+				);
+			}
+			suffix.unshift(basename(current));
+			current = parent;
+		}
+	}
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) {
+		throw new ImageGenerationError("aborted", "Image generation was cancelled.");
+	}
+}
+
+export function getGeneratedImagesRoot(agentDir: string): string {
+	return join(resolve(agentDir), "generated-images");
+}
+
+export async function prepareExplicitOutputPath(args: {
+	rawPath?: string;
+	agentDir: string;
+	ctx: Pick<ExtensionContext, "cwd" | "hasUI" | "isProjectTrusted" | "ui">;
+	signal?: AbortSignal;
+}): Promise<ExplicitOutputPlan | undefined> {
+	if (args.rawPath === undefined) return undefined;
+	const trimmed = args.rawPath.trim();
+	if (!trimmed || trimmed.length > MAX_IMAGE_PATH_CHARS || extname(trimmed).toLowerCase() !== ".png") {
+		throw new ImageGenerationError(
+			"output-path-invalid",
+			"outputPath must be a non-empty .png file path.",
+		);
+	}
+
+	throwIfAborted(args.signal);
+	const lexical = isAbsolute(trimmed) ? resolve(trimmed) : resolve(args.ctx.cwd, trimmed);
+	const target = await resolveWriteTarget(lexical);
+	const targetInfo = await stat(target).catch(() => undefined);
+	if (targetInfo) {
+		throw new ImageGenerationError(
+			"output-path-invalid",
+			`Output path already exists and will not be overwritten: ${target}`,
+		);
+	}
+
+	const [agentRoot, projectRoot] = await Promise.all([
+		realDirectory(args.agentDir),
+		realDirectory(args.ctx.cwd),
+	]);
+	if (isPathInsideOrEqual(agentRoot, target)) return { path: target };
+
+	if (isPathInsideOrEqual(projectRoot, target)) {
+		if (!args.ctx.isProjectTrusted()) {
+			throw new ImageGenerationError(
+				"output-path-invalid",
+				"Writing generated images inside an untrusted project is not allowed.",
+			);
+		}
+		return { path: target };
+	}
+
+	if (!args.ctx.hasUI) {
+		throw new ImageGenerationError(
+			"output-path-approval-required",
+			"Writing outside the Pi agent root or trusted project requires interactive approval.",
+		);
+	}
+	const approved = await args.ctx.ui.confirm(
+		"Write generated image outside safe roots?",
+		[
+			"The generated PNG will be copied to this external path without overwriting an existing file:",
+			"",
+			target,
+			"",
+			"Continue?",
+		].join("\n"),
+		{ signal: args.signal },
+	);
+	throwIfAborted(args.signal);
+	if (!approved) {
+		throw new ImageGenerationError("output-path-declined", "External output path was declined.");
+	}
+	return { path: target };
+}
+
+async function publishBytesNoOverwrite(bytes: Uint8Array, target: string): Promise<void> {
+	const parent = dirname(target);
+	await mkdir(parent, { recursive: true });
+	const tempPath = join(parent, `.${basename(target)}.${randomUUID()}.tmp`);
+	let handle: Awaited<ReturnType<typeof open>> | undefined;
+	try {
+		handle = await open(tempPath, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
+		await handle.writeFile(bytes);
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		await link(tempPath, target);
+	} finally {
+		await handle?.close().catch(() => undefined);
+		await unlink(tempPath).catch(() => undefined);
+	}
+}
+
+function isAlreadyExistsError(error: unknown): boolean {
+	return !!error && typeof error === "object" && "code" in error && error.code === "EEXIST";
+}
+
+export async function saveCanonicalImage(args: {
+	bytes: Uint8Array;
+	agentDir: string;
+	sessionId: string;
+	imageCallId: string;
+}): Promise<string> {
+	const root = getGeneratedImagesRoot(args.agentDir);
+	const sessionPart = sanitizePathPart(args.sessionId, "session");
+	const imagePart = sanitizePathPart(args.imageCallId, "image_generation");
+	const directory = join(root, sessionPart);
+
+	for (let index = 1; index <= 1000; index += 1) {
+		const suffix = index === 1 ? "" : `-${index}`;
+		const target = join(directory, `${imagePart}${suffix}.png`);
+		try {
+			await publishBytesNoOverwrite(args.bytes, target);
+			return target;
+		} catch (error) {
+			if (isAlreadyExistsError(error)) continue;
+			throw new ImageGenerationError(
+				"artifact-write-failed",
+				sanitizeImageDiagnostic(
+					error instanceof Error ? error.message : error,
+					"Failed to persist the generated image artifact.",
+				),
+			);
+		}
+	}
+	throw new ImageGenerationError(
+		"artifact-write-failed",
+		"Failed to reserve a unique generated image artifact path.",
+	);
+}
+
+export async function copyImageToExplicitPath(args: {
+	bytes: Uint8Array;
+	plan: ExplicitOutputPlan;
+}): Promise<void> {
+	const currentTarget = await resolveWriteTarget(args.plan.path);
+	if (currentTarget !== args.plan.path) {
+		throw new Error("Output path changed after approval.");
+	}
+	await publishBytesNoOverwrite(args.bytes, args.plan.path);
+}
+
+export const _artifactTest = {
+	isPathInsideOrEqual,
+	publishBytesNoOverwrite,
+	resolveWriteTarget,
+};