Skip to content

Commit e5d1dd1

Browse files
committed
fix(openai-responses): round-trip image-gen namespace
Lower Codex's private image_gen namespace to safe API-key aliases, restore function calls in JSON and SSE responses, and encode replayed history without changing ChatGPT forward mode.
1 parent 903b62c commit e5d1dd1

10 files changed

Lines changed: 825 additions & 88 deletions

File tree

‎docs-site/src/content/docs/guides/codex-integration.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,14 @@ Standalone `/images/generations` calls never enter that bridge.
6363
tool offered at all, disable it in Codex with `codex features disable image_generation`
6464
(`[features] image_generation = false` in `config.toml`).
6565

66+
The tool declaration still travels with the model's Responses request. For API-key Responses
67+
providers, opencodex lowers Codex's private `image_gen` namespace to an upstream-safe
68+
`image_gen__imagegen` alias and removes a duplicate hosted `image_generation` declaration. It maps
69+
the returned function call back to the explicit `image_gen` namespace before Codex sees it, and
70+
encodes the native call again when later history is replayed upstream. This keeps client-side image
71+
generation callable on public-compatible upstreams that reserve the namespace or reject dotted
72+
function names. ChatGPT forward mode remains untouched and keeps its native Responses Lite shape.
73+
6674
For an OpenAI-compatible custom gateway, configure a dedicated provider and select it only for
6775
standalone Images requests:
6876

‎src/adapters/openai-responses.ts‎

Lines changed: 153 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { createHash } from "node:crypto";
22
import type { IncomingMeta, ProviderAdapter } from "./base";
3-
import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
3+
import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage } from "../types";
44
import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
55
import { COMPACT_PROMPT, decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
66
import { decodeServerSentEvents } from "../lib/sse-decoder";
@@ -500,31 +500,121 @@ function stripUnsupportedForwardParams(body: unknown): unknown {
500500
return rest;
501501
}
502502

503+
const IMAGE_GEN_NAMESPACE = "image_gen";
504+
const HOSTED_IMAGE_GENERATION_TOOL = "image_generation";
505+
const IMAGE_GEN_DOTTED_PREFIX = `${IMAGE_GEN_NAMESPACE}.`;
506+
const IMAGE_GEN_WIRE_PREFIX = `${IMAGE_GEN_NAMESPACE}__`;
507+
508+
function imageGenLocalName(name: string): string {
509+
if (name.startsWith(IMAGE_GEN_DOTTED_PREFIX)) return name.slice(IMAGE_GEN_DOTTED_PREFIX.length);
510+
if (name.startsWith(IMAGE_GEN_WIRE_PREFIX)) return name.slice(IMAGE_GEN_WIRE_PREFIX.length);
511+
return name;
512+
}
513+
514+
function imageGenWireName(name: string): string {
515+
return namespacedToolName(IMAGE_GEN_NAMESPACE, imageGenLocalName(name));
516+
}
517+
518+
function isImageGenClientName(name: string): boolean {
519+
return name === IMAGE_GEN_NAMESPACE
520+
|| name.startsWith(IMAGE_GEN_DOTTED_PREFIX)
521+
|| name.startsWith(IMAGE_GEN_WIRE_PREFIX);
522+
}
523+
524+
function declaresImageGenClientTool(tool: unknown): boolean {
525+
if (!isPlainObject(tool) || typeof tool.name !== "string") return false;
526+
if (tool.type === "namespace") return tool.name === IMAGE_GEN_NAMESPACE;
527+
return isImageGenClientName(tool.name);
528+
}
529+
503530
/**
504-
* Hosted tool types whose server-side function names collide with the client tools Codex
505-
* declares for the matching app skill. Codex sends BOTH (e.g. hosted `image_generation` plus a
506-
* declared `image_gen.imagegen` function/namespace tool for the imagegen skill). The ChatGPT
507-
* backend tolerates the pair, but the platform `/v1/responses` rejects it:
508-
* `Invalid Value: 'tools'. Function 'image_gen.imagegen' conflicts with a hosted tool in the
509-
* same request.` Keyed hosted-type → conflicting client tool-name prefix; the hosted entry is
510-
* dropped (the declared tool wins — Codex executes the skill client-side either way).
531+
* Lower one complete Codex image-gen namespace to public Responses function tools.
532+
*
533+
* The public API reserves the `image_gen` namespace and restricts function names to a flat safe
534+
* alphabet. `image_gen__<tool>` is therefore an upstream-only alias; client-facing responses are
535+
* restored to explicit `{ namespace: "image_gen", name: "<tool>" }` calls by the server. Only a
536+
* non-empty namespace containing named function tools is safe to lower. Malformed, empty, and
537+
* future namespace shapes stay untouched instead of silently losing client capabilities.
511538
*/
512-
const HOSTED_TOOL_NAME_CONFLICTS: ReadonlyArray<{ hostedType: string; namePrefix: string }> = [
513-
{ hostedType: "image_generation", namePrefix: "image_gen" },
514-
];
539+
function flattenImageGenNamespace(tool: unknown): Record<string, unknown>[] | undefined {
540+
if (
541+
!isPlainObject(tool)
542+
|| tool.type !== "namespace"
543+
|| tool.name !== IMAGE_GEN_NAMESPACE
544+
|| !Array.isArray(tool.tools)
545+
|| tool.tools.length === 0
546+
) return undefined;
547+
548+
for (const innerTool of tool.tools) {
549+
if (
550+
!isPlainObject(innerTool)
551+
|| innerTool.type !== "function"
552+
|| typeof innerTool.name !== "string"
553+
|| innerTool.name.length === 0
554+
) return undefined;
555+
}
556+
557+
return tool.tools.map(innerTool => {
558+
const functionTool = innerTool as Record<string, unknown> & { name: string };
559+
return {
560+
...functionTool,
561+
name: imageGenWireName(functionTool.name),
562+
};
563+
});
564+
}
565+
566+
function normalizeFlatImageGenFunction(tool: unknown): unknown {
567+
if (
568+
!isPlainObject(tool)
569+
|| tool.type !== "function"
570+
|| typeof tool.name !== "string"
571+
|| !tool.name.startsWith(IMAGE_GEN_DOTTED_PREFIX)
572+
) return tool;
573+
return { ...tool, name: imageGenWireName(tool.name) };
574+
}
575+
576+
function imageGenFunctionName(tool: unknown): string | undefined {
577+
if (!isPlainObject(tool) || tool.type !== "function" || typeof tool.name !== "string") {
578+
return undefined;
579+
}
580+
return isImageGenClientName(tool.name) ? tool.name : undefined;
581+
}
582+
583+
function declaresImageGenFunctionCall(item: unknown): boolean {
584+
if (!isPlainObject(item) || item.type !== "function_call" || typeof item.name !== "string") {
585+
return false;
586+
}
587+
return item.namespace === IMAGE_GEN_NAMESPACE || isImageGenClientName(item.name);
588+
}
589+
590+
function normalizeImageGenFunctionCall(item: unknown): unknown {
591+
if (!declaresImageGenFunctionCall(item) || !isPlainObject(item) || typeof item.name !== "string") {
592+
return item;
593+
}
594+
if (item.namespace === IMAGE_GEN_NAMESPACE) {
595+
const { namespace: _namespace, ...rest } = item;
596+
return { ...rest, name: imageGenWireName(item.name) };
597+
}
598+
if (item.name.startsWith(IMAGE_GEN_DOTTED_PREFIX)) {
599+
return { ...item, name: imageGenWireName(item.name) };
600+
}
601+
return item;
602+
}
515603

516604
/**
517-
* Drop hosted tools whose names collide with declared function/namespace tools (see
518-
* HOSTED_TOOL_NAME_CONFLICTS). Only applies on the API-key platform path: the ChatGPT backend
519-
* ("forward" mode) accepts the pair, and stripping there would disable native imagegen. No-op
520-
* (returns the original reference) when nothing matches.
605+
* Normalize Codex's private image-gen tool declaration for API-key Responses providers.
521606
*
522-
* Codex Desktop Responses Lite requests do not always use top-level `body.tools`; they may place
523-
* the same declarations in `body.input[]` entries of type `additional_tools`. The platform validates
524-
* these containers as one tool namespace, so conflict detection must span all of them. The function
525-
* uses copy-on-write semantics and preserves the original request reference when nothing is removed.
607+
* A complete `image_gen` namespace is flattened to safe `image_gen__<tool>` aliases even when it is
608+
* the only image tool in the request. Replayed client calls are encoded to the same alias, including
609+
* legacy dotted calls from older compatibility attempts. When any client image-gen tool is present,
610+
* the duplicate hosted `image_generation` entry is removed. Duplicate aliases are resolved in stable
611+
* container order: top-level tools first, then Responses Lite `additional_tools` entries.
612+
*
613+
* This function is called only on the API-key path. ChatGPT forward mode understands the private
614+
* namespace and must keep it. Copy-on-write preserves the original request reference when no
615+
* namespace is flattened, hosted tool removed, or duplicate function discarded.
526616
*/
527-
function stripConflictingHostedTools(body: unknown): unknown {
617+
function normalizeImageGenClientTools(body: unknown): unknown {
528618
if (!isPlainObject(body)) return body;
529619

530620
// Collect every tool container in the request. Traditional HTTP/SSE requests use top-level
@@ -538,48 +628,61 @@ function stripConflictingHostedTools(body: unknown): unknown {
538628
}
539629
}
540630
}
541-
if (toolGroups.length === 0) return body;
542-
543-
// Detect conflicts across containers because the client namespace and the hosted tool may be
544-
// declared in different groups while still sharing one platform-validated namespace.
545-
const conflicting = HOSTED_TOOL_NAME_CONFLICTS.filter(c => toolGroups.some(group =>
546-
group.some(t => {
547-
if (!isPlainObject(t) || typeof t.name !== "string") return false;
548-
if (t.type === "namespace") return t.name === c.namePrefix;
549-
return t.name === c.namePrefix || t.name.startsWith(`${c.namePrefix}.`);
550-
}),
551-
));
552-
if (conflicting.length === 0) return body;
553-
554-
// Allocate a replacement only when a hosted tool is removed. Preserve malformed entries,
555-
// unrelated tools, and future tool types so this compatibility rule remains narrowly scoped.
556-
const stripGroup = (tools: unknown[]): unknown[] => {
557-
const filtered = tools.filter(t => {
558-
const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
559-
if (!type) return true;
560-
return !conflicting.some(c => c.hostedType === type);
561-
});
562-
return filtered.length === tools.length ? tools : filtered;
631+
const hasImageGenClientTool = toolGroups.some(group => group.some(declaresImageGenClientTool))
632+
|| (Array.isArray(body.input) && body.input.some(declaresImageGenFunctionCall));
633+
if (!hasImageGenClientTool) return body;
634+
635+
const seenFunctionNames = new Set<string>();
636+
const normalizeGroup = (tools: unknown[]): unknown[] => {
637+
const normalized: unknown[] = [];
638+
let groupChanged = false;
639+
640+
for (const tool of tools) {
641+
if (isPlainObject(tool) && tool.type === HOSTED_IMAGE_GENERATION_TOOL) {
642+
groupChanged = true;
643+
continue;
644+
}
645+
646+
const flattened = flattenImageGenNamespace(tool);
647+
const candidates = flattened ?? [tool];
648+
if (flattened) groupChanged = true;
649+
650+
for (const candidate of candidates) {
651+
const normalizedCandidate = normalizeFlatImageGenFunction(candidate);
652+
if (normalizedCandidate !== candidate) groupChanged = true;
653+
const functionName = imageGenFunctionName(normalizedCandidate);
654+
if (functionName && seenFunctionNames.has(functionName)) {
655+
groupChanged = true;
656+
continue;
657+
}
658+
if (functionName) seenFunctionNames.add(functionName);
659+
normalized.push(normalizedCandidate);
660+
}
661+
}
662+
663+
return groupChanged ? normalized : tools;
563664
};
564665

565666
let changed = false;
566667
let tools = body.tools;
567668
if (Array.isArray(body.tools)) {
568-
tools = stripGroup(body.tools);
669+
tools = normalizeGroup(body.tools);
569670
changed ||= tools !== body.tools;
570671
}
571672

572673
let input = body.input;
573674
if (Array.isArray(body.input)) {
574675
let nestedChanged = false;
575676
const mappedInput = body.input.map(item => {
576-
if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) {
577-
return item;
677+
if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
678+
const nestedTools = normalizeGroup(item.tools);
679+
if (nestedTools === item.tools) return item;
680+
nestedChanged = true;
681+
return { ...item, tools: nestedTools };
578682
}
579-
const nestedTools = stripGroup(item.tools);
580-
if (nestedTools === item.tools) return item;
581-
nestedChanged = true;
582-
return { ...item, tools: nestedTools };
683+
const normalizedCall = normalizeImageGenFunctionCall(item);
684+
if (normalizedCall !== item) nestedChanged = true;
685+
return normalizedCall;
583686
});
584687
if (nestedChanged) {
585688
input = mappedInput;
@@ -740,7 +843,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
740843
outBody = repairOrphanedInputItems(outBody, unexpandedMiss);
741844
outBody = stripUnsupportedForwardParams(outBody);
742845
}
743-
else outBody = stripConflictingHostedTools(outBody);
846+
else outBody = normalizeImageGenClientTools(outBody);
744847
if (forward || parsed._previousResponseInputExpanded === true) {
745848
outBody = repairOversizedReplayCallIds(outBody);
746849
}

‎src/server/index.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -226,14 +226,15 @@ function attachLiveSidebandUpstream(ws: ServerWebSocket<WsData>): void {
226226
// Source invariant for tests/passthrough-abort.test.ts after the pure module split:
227227
// if (isEventStream && upstreamResponse.body) {
228228
// const repairConfig = route.provider.responsesItemIdRepair;
229-
// #314 gated shape (win32-no-repair only; default OFF on the bundled known-bad runtime):
229+
// const needsClientRewrite = imageGenCallAliases.size > 0
230+
// #314 gated shape (win32-no-client-rewrite only; default OFF on the bundled known-bad runtime):
230231
// decideEagerRelay(config.streamMode ?? "auto")
231232
// relaySseEagerBounded(upstreamResponse.body, turnAc,
232233
// Default shape (tee + background inspection):
233234
// upstreamResponse.body.tee()
234235
// const repairedBody = hasResponsesItemIdRepair(repairConfig)
235236
// process.platform === "win32"
236-
// && !hasResponsesItemIdRepair(repairConfig)
237+
// && !needsClientRewrite
237238
// ? nativeBody
238239
// relaySseWithFailedTail(repairedBody, upstream)
239240
// new Response(clientBody

0 commit comments

Comments
 (0)