pi-openai-toolkit 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lll9p
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,33 @@
+pi-openai-toolkit
+Copyright (c) 2026 awoaCrim and contributors
+
+The native OpenAI Web Search behavior in this package was adapted from
+code-yeongyu/pi-openai-web-search at commit
+39643380682f02f306b0de2673ff136c45ccc2a2.
+
+Upstream copyright and license notice:
+
+Copyright (c) 2026 Yeongyu Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The adapted implementation targets the @earendil-works Pi interfaces and is
+integrated with pi-openai-toolkit's independent compaction and Web Search
+extension entry points. The upstream NOTICE also identifies the behavior as a
+standalone port of the senpi-mono built-in openai-web-search extension.

package/README.md

@@ -0,0 +1,175 @@
+# pi-openai-toolkit
+
+<p align="center">
+  <strong>OpenAI-focused toolkit for <a href="https://github.com/badlogic/pi">Pi</a>: Native Remote Compaction v2 & Hosted Web Search</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> | <a href="./README_zh.md">简体中文</a>
+</p>
+
+---
+
+`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:
+
+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.
+
+## Installation
+
+### Install via Pi Package Manager (recommended)
+
+```bash
+pi install npm:pi-openai-toolkit
+```
+
+### Git installation (alternative / development)
+
+```bash
+pi install git:github.com/awoaCrim/pi-openai-toolkit
+```
+
+### Local Development / Testing
+
+Load the complete toolkit:
+
+```bash
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit
+```
+
+Or load a single extension independently:
+
+```bash
+# Compaction only
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/compaction.ts
+
+# Web Search only
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/web-search.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.
+
+---
+
+## Configuration
+
+Configuration file location:
+
+```text
+~/.pi/agent/extensions/pi-openai-toolkit/config.json
+```
+
+### Example `config.json`
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "allowCompactionContinuityBreak": false,
+    "model": null,
+    "thinkingLevel": "off",
+    "responsesApis": [
+      "openai-responses",
+      "openai-codex-responses"
+    ],
+    "notifyOnLoad": false,
+    "debug": false,
+    "logProviderPayloads": false,
+    "logCompactResponses": false,
+    "redactSensitiveData": true,
+    "artifactRoot": "~/.pi/agent/artifacts/pi-openai-toolkit/compaction"
+  },
+  "webSearch": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ]
+  }
+}
+```
+
+### Configuration Options
+
+#### `compaction`
+
+- `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).
+- `model` (*string | null*, default: `null`): Fallback model formatted as `provider/model-id` (e.g. `"openai/gpt-4o-mini"`) used if the remote compact gateway fails or when switching to non-Responses APIs. If `null`, uses the session's active model.
+- `thinkingLevel` (*string*, default: `"off"`): Reasoning / thinking level passed to Pi native compaction fallback (`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`).
+- `responsesApis` (*string[]*): Narrow the supported remote compaction API identifiers (subset of `["openai-responses", "openai-codex-responses"]`).
+- `notifyOnLoad` (*boolean*, default: `false`): Show a notification banner on Pi startup.
+- `debug` (*boolean*, default: `false`): Output diagnostics and write execution artifacts to disk.
+- `logProviderPayloads` / `logCompactResponses` (*boolean*, default: `false`): Write raw provider request payloads and compact SSE event bodies to artifacts.
+- `redactSensitiveData` (*boolean*, default: `true`): Automatically redact Authorization headers, API keys, sensitive URL query tokens, and opaque `encrypted_content` ciphertext from debug artifacts.
+- `artifactRoot` (*string*): Directory root for diagnostic artifacts. Relative paths resolve against the config directory.
+
+#### `webSearch`
+
+- `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.
+
+---
+
+## Core Mechanics
+
+### 1. Remote Compaction v2 Protocol
+
+Instead of legacy JSON endpoints (`POST /responses/compact`), this toolkit implements the **`remote_compaction_v2`** protocol over standard streaming Responses:
+
+```http
+POST /responses
+Content-Type: application/json
+
+{
+  "model": "...",
+  "input": [
+    ...currentResponsesInput,
+    { "type": "compaction_trigger" }
+  ],
+  "stream": true,
+  "store": false
+}
+```
+
+- **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`.
+- **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.
+- **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. Model-Scoped Web Search
+
+For allowlisted models using `openai-responses` or `openai-codex-responses`, the extension hooks into `before_provider_request` and `before_agent_start`:
+
+- Injects `{ "type": "web_search" }` tool definition into the payload.
+- Appends `web_search_call.action.sources` to the Responses `include` array.
+- Appends concise search prompting to the system instructions.
+- **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.
+
+---
+
+## Development & Testing
+
+```bash
+# Typecheck TypeScript definitions
+npm run typecheck
+
+# Run full test suite with Bun
+bun test
+
+# Run Pi integration smoke tests
+npm run test:pi
+
+# Dry-run package archive
+npm pack --dry-run
+```
+
+---
+
+## License & Acknowledgments
+
+- Licensed under the **MIT License**. See [LICENSE](./LICENSE) for details.
+- Native Web Search behavior was adapted from [`code-yeongyu/pi-openai-web-search`](https://github.com/code-yeongyu/pi-openai-web-search) (commit `39643380682f02f306b0de2673ff136c45ccc2a2`). See [NOTICE](./NOTICE).
+- [LINUX DO](https://linux.do/) community.

package/README_zh.md

@@ -0,0 +1,172 @@
+# pi-openai-toolkit
+
+<p align="center">
+  <strong>专为 <a href="https://github.com/badlogic/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2 & 原生托管联网搜索</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> | <a href="./README_zh.md">简体中文</a>
+</p>
+
+---
+
+`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` 会话提供并拥有原生联网搜索。
+
+## 安装使用
+
+### 通过 Pi 安装 (推荐)
+
+```bash
+pi install npm:pi-openai-toolkit
+```
+
+### Git 安装（替代 / 开发路径）
+
+```bash
+pi install git:github.com/awoaCrim/pi-openai-toolkit
+```
+
+### 本地开发与调试加载
+
+加载完整工具包：
+
+```bash
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit
+```
+
+或单独加载某一子扩展：
+
+```bash
+# 仅加载远端压缩
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/compaction.ts
+
+# 仅加载原生联网搜索
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/web-search.ts
+```
+
+> ⚠️ **冲突提示**：请勿同时启用 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search`。多重钩子会产生竞态或注入重复的 System Prompt。
+
+---
+
+## 配置文件说明
+
+全局唯一配置路径：
+
+```text
+~/.pi/agent/extensions/pi-openai-toolkit/config.json
+```
+
+### 配置示例
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "allowCompactionContinuityBreak": false,
+    "model": null,
+    "thinkingLevel": "off",
+    "responsesApis": [
+      "openai-responses",
+      "openai-codex-responses"
+    ],
+    "notifyOnLoad": false,
+    "debug": false,
+    "logProviderPayloads": false,
+    "logCompactResponses": false,
+    "redactSensitiveData": true,
+    "artifactRoot": "~/.pi/agent/artifacts/pi-openai-toolkit/compaction"
+  },
+  "webSearch": {
+    "enabled": true,
+    "models": [
+      "uwoacrimson/gpt-5.6-luna"
+    ]
+  }
+}
+```
+
+### 配置参数详解
+
+#### `compaction`（压缩配置）
+
+- `enabled` (*boolean*, 默认 `true`): 是否启用远端无损压缩。
+- `allowCompactionContinuityBreak` (*boolean*, 默认 `false`): 若最近一次历史压缩由其他方式（如文本摘要）生成，设为 `true` 允许直接从当前有效文本上下文重建密文压缩链。
+- `model` (*string | null*, 默认 `null`): 降级模型，格式为 `"provider/model-id"`（例如 `"openai/gpt-4o-mini"`）。当网关不支持远端压缩或切换到非 Responses 协议模型时使用。为 `null` 时使用当前会话模型。
+- `thinkingLevel` (*string*, 默认 `"off"`): 降级模型调用 Pi 原生压缩时的思考级别（`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`）。
+- `responsesApis` (*string[]*): 允许尝试远端压缩的 API 标识符子集（从 `["openai-responses", "openai-codex-responses"]` 中选定）。
+- `notifyOnLoad` (*boolean*, 默认 `false`): Pi 启动加载时是否弹出气泡提示。
+- `debug` (*boolean*, 默认 `false`): 是否开启调试模式并记录诊断日志。
+- `logProviderPayloads` / `logCompactResponses` (*boolean*, 默认 `false`): 是否在 Artifacts 中记录完整的 Provider 请求与 SSE 流事件体。
+- `redactSensitiveData` (*boolean*, 默认 `true`): 自动对日志中的 Authorization 请求头、API Key、URL 敏感参数及 `encrypted_content` 密文进行脱敏处理（替换为 `[REDACTED]`）。
+- `artifactRoot` (*string*): 诊断日志存储根目录，支持 `~/` 路径。
+
+#### `webSearch`（联网搜索配置）
+
+- `enabled` (*boolean*, 默认 `true`): 是否启用原生 OpenAI 联网搜索注入。
+- `models` (*string[]*): 精确的 `provider/model-id` 模型白名单。只有列表中的模型在 `openai-responses` 或 `openai-codex-responses` 端点上运行时，才会使用 Toolkit Web Search。空列表表示所有模型都不启用 Toolkit Web Search。
+
+---
+
+## 核心工作原理解析
+
+### 1. Remote Compaction v2（远端密文压缩）
+
+摒弃了老旧且不稳定的 `POST /responses/compact` JSON 端点，采用最新 **`remote_compaction_v2`** 标准流式协议：
+
+```http
+POST /responses
+Content-Type: application/json
+
+{
+  "model": "...",
+  "input": [
+    ...当前会话输入上下文,
+    { "type": "compaction_trigger" }
+  ],
+  "stream": true,
+  "store": false
+}
+```
+
+- **校验标准**：接收 SSE 流并验证 `response.completed` 事件（状态为 `completed`），且返回且仅返回一个包含非空 `encrypted_content` 密文的 `type: "compaction"` 数据块。
+- **无损重放机制**：密文数据完整存入 `CompactionEntry.details.compactedWindow`。在后续对话中，插件会自动将密文插入在最新的系统指令之后与最新几轮消息之前，实现完全服务端无损上下文还原。
+- **三级优雅降级**：
+  1. 支持的 Responses 端点 &rarr; 触发 Remote v2 密文无损压缩；
+  2. 网关不支持或报错 &rarr; 降级调用用户指定的 `compaction.model`；
+  3. 未配置降级模型 &rarr; 回退至 Pi 默认的当前模型摘要压缩。
+
+### 2. 按模型启用的联网搜索
+
+对于白名单中的 `openai-responses` 或 `openai-codex-responses` 模型，扩展直接拦截请求载荷：
+
+- 自动向 `tools` 注入 `{ "type": "web_search" }`；
+- 自动向 `include` 数组追加 `web_search_call.action.sources`；
+- 注入规范、去重的搜索引导 System Prompt；
+- **零额外网络延迟**：复用 Pi 当前活跃的 Provider 配置、认证凭据与 Base URL；
+- **Toolkit 接管搜索**：对于符合条件的模型，发给 Provider 的载荷会移除名为 `web_search` 的本地 Function Tool，只保留原生搜索；切换到不符合条件的模型后，会恢复该本地工具原先的 active 状态。
+
+---
+
+## 测试与验证
+
+```bash
+# 类型检查
+npm run typecheck
+
+# 单元与集成测试 (Bun)
+bun test
+
+# Pi 冒烟测试
+npm run test:pi
+```
+
+---
+
+## 开源协议与致谢
+
+- 本项目基于 **MIT 许可证** 开源，详情见 [LICENSE](./LICENSE)。
+- 原生联网搜索特性逻辑参考并演进自 [`code-yeongyu/pi-openai-web-search`](https://github.com/code-yeongyu/pi-openai-web-search)（Commit `39643380682f02f306b0de2673ff136c45ccc2a2`）。详细版权声明与 MIT 许可授权请参阅 [NOTICE](./NOTICE)。
+- [LINUX DO](https://linux.do/) community.

package/extensions/compaction.ts

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

package/extensions/web-search.ts

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

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "pi-openai-toolkit",
+  "version": "0.3.0",
+  "private": false,
+  "type": "module",
+  "description": "OpenAI-focused Pi toolkit providing remote Responses compaction and native Web Search.",
+  "author": "awoaCrim and contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awoaCrim/pi-openai-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/awoaCrim/pi-openai-toolkit/issues"
+  },
+  "homepage": "https://github.com/awoaCrim/pi-openai-toolkit#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "openai",
+    "compaction",
+    "web-search",
+    "codex",
+    "responses"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/compaction.ts",
+      "./extensions/web-search.ts"
+    ]
+  },
+  "files": [
+    "extensions/compaction.ts",
+    "extensions/web-search.ts",
+    "src/compact-client.ts",
+    "src/config.ts",
+    "src/debug.ts",
+    "src/details-store.ts",
+    "src/extension-runtime.ts",
+    "src/native-fallback.ts",
+    "src/payload-rewrite.ts",
+    "src/provider-headers.ts",
+    "src/remote-v2-client.ts",
+    "src/request-context-cache.ts",
+    "src/runtime.ts",
+    "src/serializer.ts",
+    "src/supported-environment.ts",
+    "src/types.ts",
+    "src/web-search/extension.ts",
+    "src/web-search/payload.ts",
+    "src/web-search/prompt.ts",
+    "src/web-search/types.ts",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    "NOTICE",
+    "tsconfig.check.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=text --coverage-reporter=lcov && node ./scripts/check-lcov.mjs ./coverage/lcov.info",
+    "test:pi": "bun test ./test/pi-smoke.test.ts",
+    "typecheck": "tsc -p tsconfig.check.json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=0.80.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "bun": "1.2.23",
+    "typescript": "5.9.3"
+  }
+}