@oai404iao/pi-codex-minimal-tools

Codex-specific Responses support for Pi, driven by an exact per-model JSON catalog instead of model-name heuristics.

Peer floor: Pi 0.85.1; tested against 0.85.1.

npm identity stays @oai404iao/pi-codex-minimal-tools. This checkout composes core, web-search and imagegen through a shared runtime. The four new packages are alpha bootstrap candidates. Guarded bundle publication remains blocked until those dependencies are bootstrapped and separately activated. Previously published tarballs are unchanged. See package composition for local installation tests and version/lifecycle restrictions; this is not a new npm release.

Compatibility boundary: Responses Lite uses an internal Codex request shape. This package pins and tests a compatibility serialization for exact configured model profiles, but it is not an OpenAI-supported public API contract and may stop working if that internal protocol changes.

The extension adds:

• Responses SSE, WebSocket, cached continuation, WebSocket retry, upgrade-only SSE fallback, and WebSocket prewarm.
• Standard Responses and the internal Codex Responses Lite envelope.
• Codex freeform apply_patch, including streaming preview and exact replay.
• Hosted Responses web search or standalone Codex web.run.
• Hosted Responses image generation or standalone Codex image_gen.imagegen.
• Codex remote compaction v2 and legacy /responses/compact.
• Per-model Fast service tiers.
• User overrides and user-added provider/model profiles.

Unknown models are not guessed. They keep Pi's native provider implementation and do not receive package tools.

Codex Identity

This package owns Codex wire identity independently from Pi's session-file id:

• a root has SessionId === ThreadId;
• subagents share the root SessionId and receive their own ThreadId;
• prompt_cache_key is the shared SessionId;
• x-client-request-id is the current ThreadId;
• TurnId and x-codex-turn-state are scoped to one logical agent turn;
• WindowId is thread-scoped and advances after successful compaction;
• the installation UUIDv4 is stored at <PI_CODING_AGENT_DIR>/pi-codex-minimal-tools/installation_id.

SSE, Responses Lite, WebSocket, native compaction, and standalone web.run are projections of the same request identity snapshot.

The package also exports @oai404iao/pi-codex-minimal-tools/subagent-inline. Its named inline extension installs only identity lifecycle hooks for SDK-created child sessions; it does not register providers, tools, commands, or renderers.

Install

After the reviewed split-package alpha and its dependencies are available on npm:

pi install npm:@oai404iao/pi-codex-minimal-tools@1.4.1-alpha.0

Until then, test a complete repository checkout after running the root npm ci --ignore-scripts; an isolated bundle source directory cannot supply its unpublished workspace dependencies:

pi install /absolute/path/to/pi-codex-minimal-tools

Restart Pi or run /reload.

Commands

Command	Action
/codex-minimal-tools	Show the active model profile and effective capabilities.
/codex-minimal-tools:doctor	Show config/catalog diagnostics.
/fast [on|off|status]	Toggle the active profile's Fast service tier.
/image-gen <prompt> [@reference.png]	Run background image generation or editing.

Two Configuration Files

There are two separate model-related files:

1. Pi's agent models.json defines providers and actual models: API type, base URL, authentication, headers, modalities, context window, and cost.
2. This extension's models.json defines Codex behavior for an exact provider/model ID: Responses mode, reasoning summary, transport, tools, compaction, and Fast.

Typical paths:

<PI_CODING_AGENT_DIR>/models.json
<PI_CODING_AGENT_DIR>/extensions/pi-codex-minimal-tools/models.json
<PI_CODING_AGENT_DIR>/extensions/pi-codex-minimal-tools/config.json

Without PI_CODING_AGENT_DIR, Pi normally uses ~/.config/pi/agent or ~/.pi/agent, depending on the installation.

Extension Global Config

config.json now contains only package-wide preferences:

{
  "$schema": "https://unpkg.com/@oai404iao/pi-codex-minimal-tools@1/config.schema.json",
  "enabled": true,
  "glyphStyle": "unicode",
  "autoEnable": true,
  "webSocketEnabled": true,
  "fastMode": false,
  "imageGeneration": true,
  "imageOutputDir": ".pi/openai-codex-images",
  "imageModel": "gpt-image-2",
  "directImageApiFallback": false,
  "viewImageWorkspaceOnly": false,
  "deferApplyPatchRendering": false
}

Setting	Meaning
enabled	Enable all package behavior.
glyphStyle	Use unicode or ascii UI glyphs.
autoEnable	Add supported package tools automatically.
webSocketEnabled	Global Responses WebSocket master switch. Set false to force SSE and disable WebSocket prewarm for every model profile.
fastMode	Global user toggle; only profiles with fast are affected.
imageGeneration	Global master switch. Set false to omit image tools, /image-gen, presentation, hosted injection, standalone requests, and direct fallback without changing other model behavior.
imageOutputDir	Generated-image output directory. Relative paths resolve from the workspace root.
imageModel	Image model used by standalone/hosted image requests and direct fallback.
directImageApiFallback	Permit the separate OPENAI_API_KEY Images API fallback.
viewImageWorkspaceOnly	Restrict view_image to the workspace.
deferApplyPatchRendering	Use Pi's fallback renderer instead of the streaming patch preview.

The older model-level keys remain readable for one migration version, but are deprecated and no longer appear in config.schema.json. imageGeneration is the exception: it remains the supported global master switch. See Legacy migration.

Per-Model Catalog

Create:

<PI_CODING_AGENT_DIR>/extensions/pi-codex-minimal-tools/models.json

Example overriding a bundled model and adding a custom provider/model:

{
  "$schema": "https://unpkg.com/@oai404iao/pi-codex-minimal-tools@1/models.schema.json",
  "version": 1,
  "models": [
    {
      "id": "openai/gpt-5.5",
      "responses": {
        "reasoningSummary": "none",
        "transport": "sse",
        "websocketPrewarm": false
      },
      "tools": {
        "webSearch": false
      }
    },
    {
      "id": "my-provider/my-codex-model",
      "extends": "openai/gpt-5.5",
      "responses": {
        "endpoint": "openai",
        "transport": "websocket-cached"
      },
      "tools": {
        "imageGeneration": false
      }
    }
  ]
}

Resolution rules:

• IDs are exact, case-insensitive provider/model matches.
• A user entry with the same ID deep-overrides the bundled entry.
• extends can inherit from a bundled or user profile.
• Objects merge recursively; arrays replace the inherited array.
• Duplicate IDs, malformed JSON, missing parents, cycles, and unknown fields are reported by /codex-minimal-tools:doctor.
• Each effective profile has a stable hash. WebSocket continuation, sticky fallback, and native-compaction replay are isolated by that hash.

Full field documentation is in reference/model-catalog.md, and editor validation is provided by models.schema.json.

Custom Provider Example

The custom model must exist in Pi's agent models.json. For provider-shim features, its Pi api must be openai-responses or openai-codex-responses:

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://api.example.com/v1",
      "apiKey": "$MY_PROVIDER_API_KEY",
      "api": "openai-responses",
      "models": [
        {
          "id": "my-codex-model",
          "name": "My Codex Model",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 272000,
          "maxTokens": 16384,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

The extension dynamically attaches only its stream handler to a selected custom provider. It does not replace the provider's URL, authentication, headers, or model definitions.

If a profile requests the provider shim but the Pi model uses another API type, wire-only features are disabled:

• hosted web/image tools;
• custom/freeform apply_patch;
• native Responses compaction;
• Fast service tiers.

Standalone web/image tools and function apply_patch can still be used when the profile enables them.

Model Profile Fields

{
  "id": "provider/model",
  "extends": "provider/parent-model",
  "enabled": true,
  "responses": {
    "providerShim": true,
    "endpoint": "auto",
    "mode": "standard",
    "reasoningSummary": "auto",
    "systemPromptPlacement": "instructions",
    "transport": "auto",
    "websocketPrewarm": true
  },
  "tools": {
    "parallelCalls": true,
    "applyPatch": "custom",
    "webSearch": {
      "implementation": "hosted",
      "contentTypes": ["text", "image"]
    },
    "imageGeneration": "standalone",
    "viewImage": false
  },
  "compaction": "responses",
  "fast": {
    "serviceTier": "priority",
    "costMultiplier": 2
  }
}

Important constraints:

• responses.reasoningSummary accepts "auto", "concise", "detailed", or "none". "none" omits reasoning.summary; when absent, Standard defaults to "auto" and Lite defaults to "none".
• responses.mode:"lite" always uses a developer message, namespace tools in additional_tools, parallel_tool_calls:false, reasoning.context:"all_turns", and strips input-image detail.
• Lite cannot use hosted web_search or hosted image_generation; choose standalone instead.
• tools.applyPatch:"custom" uses the Codex freeform grammar and requires the provider shim. "function" works as a normal Pi tool.
• responses.endpoint:"openai" uses API-key endpoint/auth semantics. "codex" uses ChatGPT/Codex endpoint/auth semantics. "auto" infers from the provider.
• compaction:"responses" uses compaction_trigger through the selected SSE/WebSocket transport. "responses-compact" uses the legacy unary endpoint. "pi" keeps Pi summaries.

Built-In Profiles

The bundled catalog is based on local Codex commit eb9dceba1a2e658142a456c5898836774835616b from August 12, 2026, with the Astra profile updated from ddea03ad049142943bdbf13e937b1d67e8c1ba0c.

Models	Responses	Web	Image	Patch	Compaction
openai-codex/gpt-6-astra	Lite, auto WS/SSE	standalone text+image	standalone	custom	responses
gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna	Lite, auto WS/SSE	standalone text+image	standalone	custom	responses
gpt-5.5, gpt-5.4	Standard, auto WS/SSE	hosted text+image	standalone	custom	responses
gpt-5.4-mini, codex-auto-review	Standard, auto WS/SSE	hosted text+image	standalone	custom	responses
gpt-5.2	Standard, auto WS/SSE	hosted text	standalone	custom	responses
legacy GPT-5/Codex entries	inherited Standard profile	profile-specific	standalone	custom	responses
gpt-4.1	Standard SSE	off	hosted	off	Pi
o4-mini	Standard SSE	off	off	off	Pi

The pre-Astra entries include equivalent openai/... and openai-codex/... IDs; the latter switch only the endpoint/auth shape to codex. Astra is bundled only for openai-codex, matching the analyzed ChatGPT subscription route. A public-API or proxy Astra deployment requires an explicit user profile for that endpoint.

Pi 0.85.1 provides the Astra model descriptor; it is now the package peer floor. The extension composes its stream shim over that provider and does not replace authentication, streams, or the model catalog. The descriptor keeps the production default at 272,000 context tokens and 128,000 output tokens. A backend-authorized larger context must be selected explicitly through Pi's provider modelOverrides; the extension does not infer that entitlement from the Astra slug.

These entries are defaults, not claims that every proxy with the same model slug supports the protocol. Override or disable a profile for the endpoint actually in use.

Web Search

tools.webSearch supports two implementations:

• hosted: rewrites the Pi placeholder to Responses {"type":"web_search"} and preserves progress, sources, results, and citation replay. Standard Responses only.
• standalone: exposes web.run as a client-executed namespace tool and calls the provider's alpha/search endpoint. It supports search/image queries, open/click/find, PDF screenshots, finance, weather, sports, and time.

Standalone search sends a bounded recent visible conversation tail, resolved Pi authentication, direct-caller/live-web settings, the active turn metadata, and the model's 10,000-token truncation budget. Search rows stay compact by default and show deduplicated source hosts; expand the tool row to inspect the raw result text.

Image Generation

Set global config.json.imageGeneration to false to disable the entire generation capability. Per-model tools.imageGeneration:false disables only that profile. Neither setting disables image input or historical image replay.

tools.imageGeneration supports:

• hosted: Responses image_generation.
• standalone: image_gen.imagegen, backed by the provider's images/generations and images/edits endpoints.

Standalone input follows current Codex:

• required prompt;
• up to five referenced_image_paths; or
• num_last_images_to_include from 1 through 5.

Generated PNGs are saved under imageOutputDir, mirrored to latest.png, and returned to the model before the saved-path text. /image-gen selects any loaded image-capable model with an enabled catalog profile.

WebSocket And Compaction

Global config.json.webSocketEnabled:false forces sse and disables WebSocket prewarm without changing the selected per-model profile. When it is true (the default), each profile's responses.transport and responses.websocketPrewarm values apply.

transport values:

• sse: HTTP streaming only.
• websocket: reusable WebSocket; exact logical prefixes opportunistically use previous_response_id input deltas.
• websocket-cached: compatibility alias with the same safe continuation behavior.
• auto: retry transient WebSocket failures, but use sticky per-session SSE fallback only when the WebSocket upgrade is rejected with HTTP 426. Model, request, output-limit, context-limit, and post-upgrade connection errors do not change transports.

Prewarm is scheduled once per session startup (including resume/fork), in the background without delaying session initialization. If the first WebSocket request starts while prewarm is pending, it consumes that one startup handle before sending. Prewarm sends a best-effort response.create with generate:false containing only the startup system/tool/request envelope—never conversation history or the pending user message. The first real request appends its full conversation input, and later turns continue from real response IDs. A failed or timed-out prewarm is not retried on every user message. Continuation reuse always requires the new request to extend the previous logical request exactly.

Native compaction stores opaque encrypted state in the Pi session. New checkpoints replay only to the same provider, model, API, and effective profile hash. Switching any of those falls back to Pi's retained local context. Treat session files containing native compaction as sensitive data.

Apply Patch

When apply_patch activates, the extension temporarily hides Pi's edit and write tools and restores their prior positions after switching away.

The executor supports Codex @@ class/function contexts, ordered update chunks, *** Move to:, *** End of File, fuzzy matching, CRLF preservation, and atomic verification before writes. See reference/apply-patch-behavior.md.

Legacy Migration

These config.json keys are deprecated but still projected into an in-memory model override for compatibility:

Old key	New model-profile field
nativeProviderTools	responses.providerShim plus hosted/standalone tool selection
openaiTransport	responses.transport
openaiWebSocketPrewarm	responses.websocketPrewarm
compactionMode	compaction
requestProfile.responsesMode	responses.mode
requestProfile.reasoningSummary	responses.reasoningSummary
requestProfile.systemPromptPlacement	responses.systemPromptPlacement
requestProfile.patchTransport	tools.applyPatch
apiKeyMode	responses.endpoint
webSearchEnabled	tools.webSearch
viewImage	tools.viewImage
applyPatchEnabled	tools.applyPatch
additionalModelIds	one exact user catalog entry per model

Move these values to extension models.json; legacy projection is intended only as a transition path. imageGeneration is no longer a legacy projection: it is the supported global gate, while per-model selection stays in tools.imageGeneration.

Protocol Reference

reference/ documents the Codex snapshot, Responses Standard/Lite envelopes, namespace tools, WebSocket continuation, custom-tool streaming/replay, standalone web/image endpoints, compaction, and apply-patch protocol.

License and publication status

Project-authored portions are MIT-licensed, copyright 2026 oai404iao. Third-party material retains its own terms; see LICENSE and THIRD_PARTY_NOTICES.md.

The Codex namespace-tool source attribution is recorded in provenance/openai-codex-eb9dceba-reserved-tools.json. The existing bundle has configured trusted publishing, but the split-package alpha still requires dependency-first bootstrap and activation of the four new packages before guarded publication can proceed. Responses Lite remains an internal Codex compatibility path, not an OpenAI-supported public API contract.