cpa-codex-compact-bridge

中文 README

A CLIProxyAPI native plugin that preserves native Codex remote compaction for capable models and bridges remote compaction to ordinary summary calls for explicitly configured third-party models.

The problem

A single Codex provider can expose official GPT models and third-party models through the same CLIProxyAPI endpoint. Codex decides whether that provider uses local or remote compaction at the provider level, but compact capability actually varies by upstream model.

When remote compaction is enabled, Codex uses protocol-specific requests:

• legacy remote compact calls POST /v1/responses/compact;
• current remote compact appends a compaction_trigger to a streaming /v1/responses request;
• later turns replay the returned compaction state.

Native-capable endpoints understand those requests. Many third-party providers accept ordinary model requests but do not implement either compact transport or its replay state, so a long-running session fails exactly when compaction is needed.

Renaming the Codex provider to force local compaction avoids those remote requests, but it changes the behavior of every model behind that provider. Native-capable GPT models then lose their original remote path too.

The goal

Move the compact-capability decision from one provider-wide switch to explicit per-model rules inside CLIProxyAPI:

• preserve CPA's native path for models that already support remote compaction;
• bridge only the third-party models selected by the operator;
• return the compact structure Codex expects for both remote transports;
• keep later continuation usable without forwarding foreign opaque state;
• fail closed when safe continuation cannot be established.

The solution

The plugin evaluates ordered rules against the original client-requested model. The first match wins.

Codex compact request
        |
        +-- passthrough rule --> CPA native compact route --> native provider
        |
        `-- bridge rule ------> ordinary summary request --> cpa_compact_* item
                                                        |
next ordinary turn <------------------------------------'
        |
        `-- cpa_compact_* is restored as a normal user summary
            before the third-party provider translation

For a bridge rule, the plugin:

1. recognizes legacy V1, current V2, and later replay requests;
2. removes compact protocol artifacts and asks the configured summary model to summarize the current conversation window through CPA's host.model.execute path;
3. uses Codex's current local-compaction prompt by default, with an optional compact_prompt override;
4. returns a canonical compaction item marked with cpa_compact_* — V1 returns a compacted output window, while V2 returns the required SSE events;
5. converts only its own marked plaintext state back into an ordinary user summary on continuation.

For a passthrough rule, the plugin declines the request and CPA keeps its existing native route unchanged.

Scope and limitations

• This is a bridge for Codex Responses remote compaction. It is not a server-side implementation of Codex local compact and does not handle Claude Messages compaction.
• A bridged summary is designed to approximate Codex local-compaction continuity, but it is generated by the selected summary model and is not provider-native compact state.
• Native compaction items are treated as opaque and provider/model-lineage-specific. The plugin does not decrypt, translate, or migrate them.
• If a session already contains foreign native compact state, keep it on the originating compatible model or start a new session with a text handoff. Switching that session to a bridged third-party model fails closed by design.
• The encrypted_content field of a bridged item contains the plaintext summary. The cpa_compact_* ID is a compatibility marker, not encryption, authentication, or integrity protection.

Use cases

Native GPT main session with third-party sub-agents

Keep the GPT session on native passthrough while independent third-party sub-agent sessions use bridge rules. Both model classes can share one CPA endpoint without sharing opaque compact state.

Mixed model catalog behind one Codex provider

Expose native-capable and third-party models side by side. Each new session follows the rule for its requested model, so users do not need to rename the provider or toggle global compact behavior.

Status

• main CI runs plugin unit tests and go vet, builds a linux/amd64 c-shared candidate, and runs the real CPA integration suite against exact CLIProxyAPI v7.2.125 source.
• The plugin module currently uses the CLIProxyAPI v7.2.120 SDK; compatibility with v7.2.125 is covered by the integration gate.
• The integration suite covers V1, V2 HTTP/SSE, HTTP and streaming replay, WebSocket V2 continuation, fail-closed cases, and passthrough isolation.
• Real-provider test-cpa evaluations, including the native V2 / bridge V2 / local comparison, are recorded in the test matrix.
• Stable release: v0.1.2, published for linux/amd64 with a sha256sum-compatible checksum file.
• macOS, Windows, non-amd64 builds, and other CPA versions remain unverified.

Installation

Download the linux/amd64 release and verify it before extraction:

curl -LO https://github.com/patrick-fu/cpa-codex-compact-bridge/releases/download/v0.1.2/cpa-codex-compact-bridge_0.1.2_linux_amd64.zip
curl -LO https://github.com/patrick-fu/cpa-codex-compact-bridge/releases/download/v0.1.2/checksums.txt
sha256sum -c checksums.txt
unzip cpa-codex-compact-bridge_0.1.2_linux_amd64.zip

Install the extracted library under a versioned filename:

<plugin-dir>/linux/amd64/cpa-codex-compact-bridge-v0.1.2.so

Reload or restart CPA, then confirm GET /v0/management/plugins reports version 0.1.2, registered: true, and effective_enabled: true. File discovery alone may select the new path before the already loaded plugin instance is replaced.

To build from source instead:

cd plugin
go build -buildmode=c-shared -o cpa-codex-compact-bridge.so .

Use .dylib on macOS or .dll on Windows and replace the directory with the matching <GOOS>/<GOARCH>. These platforms are experimental until release CI covers them.

Configuration

plugins:
  enabled: true
  dir: /absolute/path/to/plugins
  configs:
    cpa-codex-compact-bridge:
      enabled: true
      priority: 100
      # Optional. Defaults to Codex's current local-compaction prompt.
      compact_prompt: "Summarize for the next coding agent."
      rules:
        # Explicit third-party bridge rule.
        - match: "deepseek-*"
          action: bridge
          summary_model: "deepseek-chat"
        # Native remote compact remains untouched.
        - match: "gpt-*-codex*"
          action: passthrough
      # Conservative default: do not bridge unknown models.
      on_no_match: passthrough

Rules use case-sensitive glob matching against the original client-requested model. summary_model defaults to the request model. compact_prompt defaults to the prompt embedded by this plugin; set it explicitly when the Codex client uses a custom compact prompt because remote compact requests do not transmit that client-side override.

CLIProxyAPI Home mode disables plugin executor routing, so it cannot be used with a bridge rule.

See Configuration for the full contract.

Security

The selected summary provider receives the conversation window required to generate the summary. Do not enable a bridge rule for data that provider is not allowed to process.

The plugin fails closed with compact_bridge_failed instead of forwarding an unsupported compact request or unknown native compact state. Read SECURITY.md before deployment and report vulnerabilities through a private GitHub security advisory.

CPA Plugin Store

This plugin is not yet listed in the official CPA Plugin Store, so CPA's built-in store cannot install it today.

The store-compatible v0.1.2 Release and its test-cpa validation are complete. The remaining publication step is a registry.json pull request. See the current store readiness report.

Verification

(cd plugin && go test ./... && go vet ./...)
(cd integration && CPA_SOURCE_DIR=/path/to/CLIProxyAPI go test ./... -count=1)

The integration suite builds a real CPA binary and the c-shared plugin. CI provides the pinned CPA checkout automatically.

Documentation

• Protocol contract
• Configuration
• Domain glossary
• Architecture decision: plaintext bridged compaction items
• CPA Plugin Store readiness

Contributing

See CONTRIBUTING.md and the Code of Conduct.

License and disclaimer

MIT — see LICENSE. Third-party notices are in THIRD_PARTY_NOTICES.

This is independent community software. It is not affiliated with, endorsed by, or certified by OpenAI or CLIProxyAPI. You are responsible for ensuring that your provider, account, API key, quota, and data use comply with the applicable terms.