OpenCode OpenAI Server Compaction

High-fidelity context compaction for OpenCode sessions that use the official openai provider.

This package improves OpenCode's native text compaction today and documents the path to OpenAI Responses API server-side compaction when OpenCode exposes the required request, response, and session-state extension points.

Why This Exists

OpenCode compacts long sessions by asking the active model to write a continuation summary while retaining recent messages. This works across providers, but a text summary can lose exact implementation state.

OpenAI's Responses API offers server-side compaction: the backend compacts the conversation itself and returns an opaque, encrypted compaction_summary item that carries full-fidelity conversation state. This is the same mechanism Codex CLI uses for its own compaction (codex-rs/core/src/compact_remote_request.rs), inspired by algal/pi-openai-server-compaction which does the equivalent for the Pi agent.

In the current API, the returned output is a compaction item with encrypted_content. It is opaque state: clients replay the returned context as-is instead of reading, editing, or serializing the artifact themselves.

Status

Stage 1 is implemented. The package uses only OpenCode's public plugin API to add precise continuation requirements to native compaction.

Stage 2 is not implemented. It requires OpenCode extension points that are not currently public. The package does not pretend to implement server-side compaction by making a second OpenAI request during native compaction.

Installation

Publish the package to the npm registry used by your OpenCode installation, then add it to the project or global OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["[email protected]"]
}

Restart OpenCode after changing its configuration. OpenCode installs and loads the npm package.

For an unpublished local package, publish it to a registry first. Do not also place this plugin in .opencode/plugins/; that would load it twice.

Authentication

Use OpenCode's existing OpenAI connection flow:

/connect -> OpenAI -> ChatGPT Plus/Pro or Manually enter API Key

The plugin does not read, write, log, or configure API keys, OAuth tokens, account IDs, authentication headers, or OPENAI_API_KEY. Authentication and request routing remain OpenCode's responsibility.

Stage 1: High-Fidelity Native Compaction

The plugin runs only when the most recent persisted user message has model.providerID === "openai". It does not enable based on a model name or a gpt prefix.

| Selected model | Plugin behavior | | --- | --- | | openai/gpt-5.6-* | Enabled | | openai/gpt-5.3-codex | Enabled | | cursor/gpt-* | Unchanged | | openrouter/gpt-* | Unchanged | | opencode/gpt-* | Unchanged | | Custom OpenAI-compatible provider | Unchanged |

When OpenCode decides to compact a session, the plugin:

1. Reads the persisted session messages through the OpenCode plugin client.
2. Returns immediately unless the session is scoped to the official openai provider.
3. Adds native-summary instructions that preserve the information a later agent needs to continue work.
4. Leaves OpenCode responsible for generating the summary, retaining recent messages, and auto-continuing the session.

The instructions require the summary to retain:

• User goals, explicit constraints, preferences, and unresolved questions.
• Exact paths, commands, configuration values, versions, URLs, errors, and verification results.
• Changed files and work in progress.
• Material tool results, rejected hypotheses, and incomplete work.
• The next concrete action.

The plugin does not set context_management, call /responses/compact, preserve response IDs, replay remote artifacts, change requests or headers, or suppress OpenCode's native compaction.

Stage 2: OpenAI Server-Side Compaction

The target OpenAI workflow is either automatic context management:

{
  "context_management": [
    {
      "type": "compaction",
      "compact_threshold": 200000
    }
  ]
}

or the standalone POST /responses/compact endpoint. Both return a compacted context window containing an encrypted compaction item that must be supplied unchanged on the next Responses call.

The desired OpenCode flow is:

OpenCode triggers compaction
  -> plugin reads or replaces the final Responses input
  -> OpenAI compacts the context
  -> plugin persists the opaque artifact with route and model identity
  -> plugin skips local text compaction
  -> the next request replays the artifact or previous_response_id

Current public plugin APIs cannot safely implement this flow. They do not provide all of the following:

• Access to or replacement of the final /responses request body.
• Access to response.id and compaction output items.
• Controlled session-bound plugin metadata storage.
• A reliable way to skip OpenCode's native compaction.

Calling OpenAI separately from experimental.session.compacting would produce double compaction and leaves no safe way to inject the returned artifact into the next model request. The package intentionally falls back to Stage 1 instead.

Compatibility Rules for Stage 2

If server-side compaction becomes possible, opaque state must be isolated by provider, model, and route:

• Same provider, model, and route: a remote context chain can be considered for reuse.
• openai/gpt-A to openai/gpt-B: discard the previous remote chain and start from OpenCode's local summary and retained messages.
• openai/* to another provider: leave that provider completely untouched.
• Another provider to openai/*: start a new OpenAI chain from OpenCode's persisted local state.

The project does not assume that previous_response_id or compaction artifacts are portable across models, endpoints, or authentication routes.

Development

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run

The package entry point is src/index.ts; the compiled plugin is exported from dist/index.js with declarations in dist/index.d.ts.

To publish to npm:

npm login
npm publish

For a private registry, authenticate with that registry and run:

npm publish --registry <registry-url>

Non-Goals

• Handling Cursor, OpenRouter, Azure, OpenCode Zen, or any provider other than openai.
• Inferring OpenAI identity from a model name.
• Managing credentials or creating a second credential store.
• Claiming that OpenAI-compatible gateways support the OpenAI compaction protocol.
• Cross-model reuse of opaque server-side state.
• Replacing native OpenCode compaction until a safe, official extension point exists.

References

• OpenCode plugins
• OpenCode providers
• OpenAI context management
• OpenAI compaction guide
• OpenAI Responses compaction API
• algal/pi-openai-server-compaction