pi-openai-toolkit

---

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

Install the published package globally (recommended)

pi install npm:pi-openai-toolkit

This adds the package to Pi's global settings. Verify the installation with:

pi list

To install it only for the current project, use:

pi install npm:pi-openai-toolkit --local

Git installation (alternative / development)

pi install git:github.com/awoaCrim/pi-openai-toolkit

Local Development / Testing

Load the complete toolkit:

pi --no-extensions -e /absolute/path/to/pi-openai-toolkit

Or load a single extension independently:

# 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

# 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.

---

Configuration

Configuration file location:

~/.pi/agent/extensions/pi-openai-toolkit/config.json

On Windows:

C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json

Example config.json

{
  "compaction": {
    "enabled": true,
    "allowCompactionContinuityBreak": false,
    "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
    "model": null,
    "thinkingLevel": "off",
    "autoCompaction": {
      "enabled": true,
      "continuation": "inline",
      "unsupportedFallback": "followUp"
    },
    "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"
    ]
  },
  "imageGeneration": {
    "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).
• 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").
• 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.
• autoCompaction.reserveTokens (non-negative integer, optional): Override only the automatic trigger reserve. When omitted, the active Pi compaction setting is used. Pi's keepRecentTokens remains authoritative for compactability.
• 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): Apply full sensitive-value redaction to debug artifacts. Authorization credentials, API keys/tokens, and opaque encrypted_content are always redacted even when this option is false.
• 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.

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

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:

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.
• 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 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 → Remote v2 Opaque Compaction.
  2. Gateway failure or non-Responses model → Configured compaction.model fallback.
  3. Otherwise → Pi default native text compaction.

2. Tool-Loop Auto-Compaction and Continuation

After every complete tool-call/result batch, the toolkit checks the current Pi usage threshold. It then mirrors official Pi's prepareCompaction() eligibility using Pi's exported cut-point and session-entry helpers before invoking the normal AgentSession.compact() path.

• Inline mode: On the guarded official Pi 0.84.3 host shape, compaction finishes before the next provider request and prepareNextTurnWithContext receives the newly built Pi session context. Remote v2, native fallback, replay rewriting, hook order, and deferred-tool carryover still run through their existing owners.
• Too-small sessions: Crossing the token threshold does not prove there is discardable history. If Pi has nothing to summarize, the toolkit does not call compact(), does not abort the active run, and lets the unfinished tool loop continue normally.
• Public fallback: followUp uses ExtensionAPI.sendMessage with a hidden followUp message after compaction. The turn is handled once, preventing repeated compaction/follow-up storms.
• Version guard: The private same-loop adapter is enabled only for the structurally verified official Pi 0.84.3 AgentSession. Unsupported hosts use the configured public fallback or disable automatic continuation.

3. 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.

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

# 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 for details.
• Native Web Search behavior was adapted from code-yeongyu/pi-openai-web-search (commit 39643380682f02f306b0de2673ff136c45ccc2a2). See NOTICE.
• LINUX DO community.