Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Feature]: Pre-adapter request transform hook (custom handlers on OcxParsedRequest)

Open
  • Is something wrong?
#3,459 3 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript
Domain
api, backend

Research direction

Start by reading server/responses/core.ts to understand where OcxParsedRequest is prepared and adapter.buildRequest is called, including retry and continuation paths. Then review the adapter interface and vision/eligibility.ts for the existing model capability check. Done means agreeing on a registration and context interface that applies transforms once per turn before adapter serialization; the issue asks for architectural input, so confirm the preferred design with maintainers before implementing.

Written by the indexing model from the issue text.

Description

enhancement priority: P3 provider
What are you trying to accomplish?

We are looking to run request-level optimizations such as pxpipe (converting large text blocks into images for vision-capable models to optimize token consumption) and headroom (context compression) in front of model routing.

Today, OpenCodeX acts as the universal routing layer to multiple providers (OpenAI, Anthropic, Google Antigravity, etc.). Having a way to plug in pre-adapter request transforms directly on the normalized request would allow these optimizations to work seamlessly across any provider.

What prevents this today?

Attempting to chain external proxy tools via baseUrl works for OpenAI-compatible wires, but completely breaks when routing to other providers—most notably Google / Gemini Antigravity (adapters/google.ts).

By the time an upstream HTTP request leaves OpenCodeX, adapter.buildRequest(parsed, ...) has already translated the request into that provider's proprietary wire format. An external proxy sitting on baseUrl would need to deconstruct, re-parse, and re-serialize Google's wire protocol, Anthropic's wire protocol, and Responses format separately.

In contrast, before buildRequest is invoked in server/responses/core.ts, OpenCodeX has already parsed the incoming turn into a single, provider-agnostic representation: OcxParsedRequest.

What should OpenCodex do?

Expose a clean pre-adapter request transform hook (or custom handler interface) that operates on OcxParsedRequest before adapter.buildRequest is called.

Key requirements:

  1. Single normalized format: Operates on OcxParsedRequest so transforms don't need to know anything about vendor wire formats.
  2. Applied once per turn: Executed once for the turn rather than re-running on every internal retry/continuation/replay in server/responses/core.ts that re-invokes buildRequest.
  3. Model & Provider Awareness: The transform receives context (providerName, modelId, providerConfig). This allows tools like pxpipe to inspect whether the target model accepts image input (reusing modelAcceptsImageInput from vision/eligibility.ts).
Example usage or interface

A lightweight transform handler signature:

export type RequestTransform = (
  parsed: OcxParsedRequest,
  ctx: {
    providerName: string;
    modelId: string;
    providerConfig: OcxProviderConfig;
  }
) => OcxParsedRequest | Promise<OcxParsedRequest>;

Configurable via ~/.opencodex/config.json by pointing to a custom TS/JS handler script (either globally or scoped per provider / model):

{
  "requestTransforms": [
    "./transforms/pxpipe-vision.ts"
  ],
  "providers": {
    "google-antigravity": {
      "requestTransforms": ["./transforms/custom-handler.ts"]
    }
  }
}
Alternatives or workarounds
  1. Chaining standalone proxies before/after ocx: Fails due to disparate downstream wire formats (e.g. Google's format).
  2. Private fork: Feasible but introduces ongoing merge maintenance for what could be a general-purpose extension point.
Additional context

This is functionally the inverse of OpenCodeX's existing vision/ sidecar (which converts images to text for non-vision models): here, text transforms into images for vision models or is compressed before routing.

Would you be open to a PR introducing this pre-adapter transform hook? If so, what architecture/interface would you prefer for registering custom handlers?

Dominant language
TypeScript
Stars
16.9k
Forks
1.3k
Avg merge
7h 50m
Merged PRs (30d)
645

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from lidge-jun/opencodex

All issues in lidge-jun/opencodex

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.