@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
494 lines (471 loc) • 23.3 kB
text/typescript
import { randomUUID } from "node:crypto";
import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "./base";
import { createAnthropicAdapter } from "./anthropic";
import type { AnthropicCacheRetention } from "./anthropic/cache-retention";
import { createGoogleAdapter } from "./google";
import { createOpenAIChatAdapter } from "./openai-chat";
import { createResponsesPassthroughAdapter } from "./openai-responses";
import { liftZedAdditionalTools, translateZedOpenAiStream } from "./zed-openai-stream";
import { zedDiagnosticUsage } from "./zed-diagnostic-usage";
import { adapterSupportExecutor } from "../lib/executor-physical-send-receipt";
import { createAdapterPhysicalSend } from "./physical-send";
import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../types";
import { createTranslatorBudget, releaseTranslatedEvent, retainTranslatedEvent, type TranslatorBudget } from "../lib/translator-budget";
import { releaseCompactionCiphertextLease } from "../responses/compaction";
import { redactSecretString } from "../lib/redact";
import {
normalizeZedProvider,
resolveZedModels,
scrubZedCredentials,
zedLlmFetch,
ZED_CLOUD_BASE_URL,
ZED_HEADERS,
type ZedCredentials,
} from "../providers/zed";
export type ZedProvider = "anthropic" | "open_ai" | "google" | "x_ai";
interface ZedDelegate {
provider: ZedProvider;
adapter: ProviderAdapter;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return !!value && typeof value === "object" && !Array.isArray(value);
}
function zedCredentials(provider: OcxProviderConfig, parsed: OcxParsedRequest): ZedCredentials {
const accessToken = provider.apiKey?.trim();
const userId = parsed._zedAuthContext?.userId?.trim();
if (!accessToken) throw new Error("Zed access token missing — run ocx login zed");
if (!userId) throw new Error("Zed account identity missing — run ocx login zed again");
return { userId, accessToken };
}
function delegateProvider(provider: OcxProviderConfig, zedProvider: ZedProvider): OcxProviderConfig {
const common: OcxProviderConfig = {
...provider,
authMode: "key",
apiKey: "zed-delegate-placeholder",
models: undefined,
liveModels: false,
// The anthropic delegate names api.anthropic.com only to borrow its body builder; the wire goes
// to Zed, which is not the first-party host the Advisor server tool defaults to (#8448).
forwardAdvisorTool: false,
};
if (zedProvider === "anthropic") {
return { ...common, adapter: "anthropic", baseUrl: "https://api.anthropic.com" };
}
if (zedProvider === "google") {
return { ...common, adapter: "google", baseUrl: "https://generativelanguage.googleapis.com", googleMode: "ai-studio" };
}
if (zedProvider === "open_ai") {
// The builder targets Zed's /completions envelope. Keep its destination set to Zed as well,
// so OpenAI-private Responses fields are stripped instead of being sent through to Zed.
return { ...common, adapter: "openai-responses", baseUrl: provider.baseUrl };
}
return { ...common, adapter: "openai-chat", baseUrl: "https://api.x.ai/v1" };
}
function forceStreaming(parsed: OcxParsedRequest): OcxParsedRequest {
const rawBody = isRecord(parsed._rawBody) ? { ...parsed._rawBody, stream: true } : parsed._rawBody;
return { ...parsed, stream: true, _rawBody: rawBody };
}
/**
* Promote the current turn's additional_tools before the Responses delegate repairs input.
* Repair can drop a replayed reasoning item and slide the wrapper under the original prefix
* length, which then hides the current catalog. The caller's raw body stays untouched.
*/
function promoteOpenAiToolsBeforeRepair(parsed: OcxParsedRequest): OcxParsedRequest {
if (!isRecord(parsed._rawBody)) return forceStreaming(parsed);
const raw = parsed._rawBody;
const copy: Record<string, unknown> = { ...raw, stream: true };
if (Array.isArray(raw.input)) {
copy.input = raw.input.map(item => (
isRecord(item) && item.type === "additional_tools" && Array.isArray(item.tools)
? { ...item, tools: [...item.tools] }
: item
));
}
if (Array.isArray(raw.tools)) copy.tools = [...raw.tools];
liftZedAdditionalTools(copy, parsed._replayPrefixLen ?? 0);
return { ...parsed, stream: true, _rawBody: copy };
}
function providerFromCatalog(catalog: Awaited<ReturnType<typeof resolveZedModels>> | undefined, model: string): ZedProvider {
const raw = catalog?.rawById.get(model);
return normalizeZedProvider(raw?.provider, model);
}
function nativeErrorPayload(provider: ZedProvider, message: string): Record<string, unknown> {
if (provider === "anthropic") {
return { type: "error", error: { type: "api_error", message } };
}
if (provider === "open_ai") {
return { type: "error", error: { message } };
}
return { error: { message } };
}
function nativeTerminalPayload(provider: ZedProvider): Record<string, unknown> {
if (provider === "anthropic") return { type: "message_stop" };
if (provider === "google") return { candidates: [{ finishReason: "STOP" }] };
if (provider === "open_ai") return { type: "response.completed", response: { output: [] } };
return { choices: [{ delta: {}, finish_reason: "stop" }] };
}
function normalizedStatus(value: unknown): { type: string; message?: string } | undefined {
if (typeof value === "string") return { type: value };
if (!isRecord(value)) return undefined;
if (typeof value.type === "string") {
return {
type: value.type,
...(typeof value.message === "string" ? { message: value.message } : {}),
};
}
const first = Object.entries(value)[0];
if (!first) return undefined;
const [type, body] = first;
if (isRecord(body)) {
return { type, ...(typeof body.message === "string" ? { message: body.message } : {}) };
}
return { type };
}
/** One Zed frame larger than this without a newline is treated as a broken stream, not buffered forever. */
const MAX_ZED_FRAME_CHARS = 1024 * 1024;
/** Whether a delegated native event is itself that protocol's terminal event. */
function isNativeTerminalEvent(event: Record<string, unknown>): boolean {
if (event.type === "message_stop") return true;
if (event.type === "response.completed" || event.type === "response.incomplete" || event.type === "response.failed") return true;
if (Array.isArray(event.choices) && event.choices.some(choice => isRecord(choice) && choice.finish_reason != null)) return true;
return Array.isArray(event.candidates) && event.candidates.some(candidate => isRecord(candidate) && candidate.finishReason != null);
}
/**
* Translate Zed's NDJSON/SSE completion frames into the delegated provider's native SSE.
*
* The request declares support for the stream-ended status, so a well-formed response ends with
* an explicit terminal status (or `[DONE]`). The stream fails closed instead of synthesizing a
* success when that guarantee is broken: a malformed or non-object frame, a frame over
* `MAX_ZED_FRAME_CHARS`, a partial trailing frame, or an EOF with neither a terminal status nor a
* native terminal event becomes the provider-native error. Nothing is forwarded after a terminal
* status or `[DONE]`; frames after a native terminal event still pass, because some wires (Chat
* with usage) send a usage chunk after `finish_reason`. Upstream failure text goes through
* `scrub`, which removes this account's token and user id.
*/
export function zedEventStream(
body: ReadableStream<Uint8Array>,
provider: ZedProvider,
scrub: (text: string) => string = redactSecretString,
): ReadableStream<Uint8Array> {
const decoder = new TextDecoder();
const encoder = new TextEncoder();
let buffer = "";
let finished = false;
let sawNativeTerminal = false;
const output = new TransformStream<Uint8Array, Uint8Array>({
transform(chunk, controller) {
if (finished) return;
const decoded = decoder.decode(chunk, { stream: true });
buffer += decoded;
let start = 0;
// A drained suffix has no newline; only new text can complete a frame.
let newline = decoded.includes("\n") ? buffer.indexOf("\n", start) : -1;
while (newline >= 0 && !finished) {
processLine(buffer.slice(start, newline), controller);
start = newline + 1;
newline = buffer.indexOf("\n", start);
}
buffer = finished ? "" : buffer.slice(start);
if (!finished && buffer.length > MAX_ZED_FRAME_CHARS) {
buffer = "";
fail(controller, "Zed stream frame exceeded the size limit");
}
},
flush(controller) {
if (finished) return;
buffer += decoder.decode();
if (buffer.trim()) {
buffer = "";
fail(controller, "Zed stream ended inside a partial frame");
return;
}
if (sawNativeTerminal) emit(controller, nativeTerminalPayload(provider));
else fail(controller, "Zed stream ended before completion");
},
});
function emit(controller: TransformStreamDefaultController<Uint8Array>, payload: Record<string, unknown>): void {
controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
}
function fail(controller: TransformStreamDefaultController<Uint8Array>, message: string): void {
emit(controller, nativeErrorPayload(provider, message));
finished = true;
}
function processLine(line: string, controller: TransformStreamDefaultController<Uint8Array>): void {
let text = line.replace(/\r$/, "").trim();
if (!text) return;
if (text.startsWith("data:")) text = text.slice(5).trimStart();
if (!text || text.startsWith(":") || text.startsWith("event:")) return;
if (text === "[DONE]") {
emit(controller, nativeTerminalPayload(provider));
finished = true;
return;
}
let parsed: unknown;
try { parsed = JSON.parse(text) as unknown; } catch {
fail(controller, "Zed stream sent a malformed frame");
return;
}
if (!isRecord(parsed)) {
fail(controller, "Zed stream sent a malformed frame");
return;
}
if (Object.hasOwn(parsed, "status")) {
const status = normalizedStatus(parsed.status);
if (status?.type === "failed" || status?.type === "error") {
fail(controller, status.message ? scrub(status.message) : "Zed request failed");
} else if (status?.type === "stream_ended" || status?.type === "completed") {
emit(controller, nativeTerminalPayload(provider));
finished = true;
}
return;
}
const event = Object.hasOwn(parsed, "event") ? parsed.event : parsed;
if (!isRecord(event)) {
fail(controller, "Zed stream sent a malformed frame");
return;
}
if (isNativeTerminalEvent(event)) sawNativeTerminal = true;
// Native diagnostics can echo the same account credential as status failures.
const diagnostic = Object.hasOwn(event, "error") || event.type === "response.failed" || event.type === "response.incomplete"
|| event.type === "error" || (isRecord(event.response) && Object.hasOwn(event.response, "error"));
const scrubFields = (record: Record<string, unknown>, preserveType = false): Record<string, unknown> => Object.fromEntries(
Object.entries(record).map(([key, value]) => [key, typeof value === "string" && !(preserveType && key === "type") ? scrub(value) : value]),
);
const scrubRecord = (record: Record<string, unknown>, preserveType = false): Record<string, unknown> => ({
...scrubFields(record, preserveType),
...(provider === "open_ai" ? { usage: zedDiagnosticUsage(record.usage) } : {}),
...(typeof record.error === "string" ? { error: scrub(record.error) }
: isRecord(record.error) ? { error: { ...scrubFields(record.error), metadata: undefined } } : {}),
...(isRecord(record.incomplete_details) ? { incomplete_details: scrubFields(record.incomplete_details) } : {}),
});
emit(controller, diagnostic ? {
...scrubRecord(event, true),
...(isRecord(event.response) ? { response: scrubRecord(event.response) } : {}),
} : event);
}
return body.pipeThrough(output);
}
function createDelegate(provider: OcxProviderConfig, zedProvider: ZedProvider, cacheRetention?: AnthropicCacheRetention): ProviderAdapter {
const config = delegateProvider(provider, zedProvider);
// The delegate only borrows the api.anthropic.com body builder; the wire goes to Zed's
// gateway, which does not document the 1h TTL, so an omitted retention stays 5m here.
if (zedProvider === "anthropic") return createAnthropicAdapter(config, cacheRetention ?? "short");
if (zedProvider === "google") return createGoogleAdapter(config);
if (zedProvider === "open_ai") return createResponsesPassthroughAdapter(config);
return createOpenAIChatAdapter(config);
}
export function createZedAdapter(provider: OcxProviderConfig, cacheRetention?: AnthropicCacheRetention): ProviderAdapter {
let delegate: ZedDelegate | undefined;
let credentials: ZedCredentials | undefined;
const buildRequest = async (parsed: OcxParsedRequest, incoming?: IncomingMeta): Promise<AdapterRequest> => {
credentials = zedCredentials(provider, parsed);
const threadId = parsed._clientThreadId ?? parsed._codexOwnThreadId ?? parsed.previousResponseId ?? randomUUID();
const promptId = randomUUID();
let catalog: Awaited<ReturnType<typeof resolveZedModels>> | undefined;
try {
const catalogTimeout = AbortSignal.timeout(8_000);
const catalogSignal = incoming?.abortSignal ? AbortSignal.any([incoming.abortSignal, catalogTimeout]) : catalogTimeout;
catalog = await resolveZedModels(
credentials,
{ signal: catalogSignal, ...(incoming?.providerFetch ? { fetchFn: incoming.providerFetch } : {}) },
);
} catch {
/* Model inference fallback below; a transient catalog outage must not block passthrough. */
}
const zedProvider = providerFromCatalog(catalog, parsed.modelId);
const selected = createDelegate(provider, zedProvider, cacheRetention);
const safeIncoming: IncomingMeta = {
headers: incoming?.headers ?? new Headers(),
translatorBudget: incoming?.translatorBudget ?? createTranslatorBudget(),
...(incoming?.providerFetch ? { providerFetch: incoming.providerFetch } : {}),
...(incoming?.abortSignal ? { abortSignal: incoming.abortSignal } : {}),
};
const delegateParsed = zedProvider === "open_ai" ? promoteOpenAiToolsBeforeRepair(parsed) : forceStreaming(parsed);
const built = await selected.buildRequest(delegateParsed, safeIncoming);
let providerRequest: unknown;
try { providerRequest = JSON.parse(built.body) as unknown; } catch { throw new Error("Zed delegate produced an invalid request body"); }
if (zedProvider === "google" && isRecord(providerRequest)) delete providerRequest.safetySettings;
if (zedProvider === "anthropic" && isRecord(providerRequest) && Array.isArray(providerRequest.messages)) {
providerRequest.messages = providerRequest.messages.map((m: unknown) => {
if (isRecord(m) && typeof m.content === "string") {
return { ...m, content: [{ type: "text", text: m.content }] };
}
return m;
});
}
if (zedProvider === "open_ai" && isRecord(providerRequest)) {
if (typeof providerRequest.input === "string") {
providerRequest.input = [
{
type: "message",
role: "user",
content: [{ type: "input_text", text: providerRequest.input }],
},
];
} else if (Array.isArray(providerRequest.input)) {
providerRequest.input = providerRequest.input.map((item: unknown) => {
if (isRecord(item)) {
const role = typeof item.role === "string" ? item.role : "user";
const type = typeof item.type === "string" ? item.type : "message";
if (typeof item.content === "string") {
return { ...item, type, role, content: [{ type: "input_text", text: item.content }] };
}
if (Array.isArray(item.content)) {
return {
...item,
type,
role,
content: item.content.map((c: unknown) => {
if (isRecord(c) && c.type === "text") {
return { ...c, type: "input_text" };
}
return c;
}),
};
}
return { ...item, type, role };
}
return item;
});
}
}
if (!isRecord(providerRequest)) throw new Error("Zed delegate produced a non-object request body");
if (zedProvider === "open_ai" && Array.isArray(providerRequest.input)) {
// Zed's OpenAI Responses parser accepts user/assistant/system/tool roles but rejects
// OpenAI's newer developer role. System is the closest supported role for instructions.
providerRequest.input = providerRequest.input.map(item =>
isRecord(item) && item.type === "message" && item.role === "developer"
? { ...item, role: "system" }
: item,
);
}
// OpenAI wrappers were promoted before delegation; serialized input has no provenance tags.
if (zedProvider === "open_ai" && Array.isArray(providerRequest.tools)) {
// Zed's Responses decoder supports function/custom tools, not Codex's built-in web_search.
const supported = (tool: unknown) => isRecord(tool) && (tool.type === "function" || tool.type === "custom");
const tools = providerRequest.tools.filter(supported);
providerRequest.tools = tools;
const choice = providerRequest.tool_choice;
if (isRecord(choice) && choice.type === "allowed_tools" && Array.isArray(choice.tools)) {
const allowed = choice.tools.filter(supported);
providerRequest.tool_choice = allowed.length ? { ...choice, tools: allowed } : "none";
} else if ((isRecord(choice) && !supported(choice)) || (choice === "required" && tools.length === 0)) {
// Match the shared hosted-tool policy when no supported selection remains.
providerRequest.tool_choice = "none";
}
}
delegate = { provider: zedProvider, adapter: selected };
const requestUrl = `${provider.baseUrl.replace(/\/+$/, "")}/completions`;
return {
url: requestUrl,
method: "POST",
headers: {
"Content-Type": "application/json",
Accept: "application/x-ndjson, text/event-stream, */*",
"User-Agent": "OpenCodex/zed",
"x-zed-version": "0.200.0",
[ZED_HEADERS.clientSupportsStatus]: "true",
[ZED_HEADERS.clientSupportsStreamEnded]: "true",
},
body: JSON.stringify({
thread_id: threadId,
prompt_id: promptId,
provider: zedProvider,
model: parsed.modelId,
provider_request: providerRequest,
}),
...(built.tierLog ? { tierLog: built.tierLog } : {}),
};
};
const adapter: ProviderAdapter = {
name: "zed",
formatErrorBody(status, _headers, payloadText) {
let payload: unknown;
try { payload = JSON.parse(payloadText) as unknown; } catch { payload = undefined; }
const record = isRecord(payload) ? payload : undefined;
const error = isRecord(record?.error) ? record.error : undefined;
const code = typeof record?.code === "string" ? record.code : typeof error?.code === "string" ? error.code : "";
const message = typeof record?.message === "string" ? record.message
: typeof error?.message === "string" ? error.message
: "Zed upstream request failed";
const scrub = (text: string) => credentials ? scrubZedCredentials(text, credentials) : redactSecretString(text);
return `Zed${code ? ` ${scrub(code)}` : ""}: ${scrub(message)} (HTTP ${status})`;
},
buildRequest,
async fetchResponse(request, ctx) {
if (!credentials) throw new Error("Zed request credentials were not initialized");
const fetchFn = adapterSupportExecutor(ctx?.executor ?? globalThis.fetch);
const send = createAdapterPhysicalSend(ctx);
let completionAttempts = 0;
return zedLlmFetch(credentials, "/completions", {
fetchFn: (async (input, init) => {
const url = input instanceof Request ? input.url : new URL(String(input)).href;
// Token exchange/account lookup are support traffic; both completion attempts
// share admission and physical ordinals, including the provider's 401 replay.
if (url === `${ZED_CLOUD_BASE_URL}/client/users/me`
|| url === `${ZED_CLOUD_BASE_URL}/client/llm_tokens`) return fetchFn(input, init);
const recovery = completionAttempts++ > 0;
return send({ url, sendClass: recovery ? "auth-recovery" : "initial",
...(recovery ? { recovery: "oauth-401" } : {}),
dispatch: executor => executor(input, init),
});
}) as typeof globalThis.fetch,
signal: ctx?.abortSignal,
baseUrl: provider.baseUrl,
fetchInit: {
method: request.method,
headers: request.headers,
body: request.body,
},
});
},
async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator<AdapterEvent> {
if (!response.body) {
yield { type: "error", message: "Zed response had no body" };
return;
}
if (!delegate) {
yield { type: "error", message: "Zed response arrived before request translation" };
return;
}
const requestCredentials = credentials;
const scrub = (text: string) => requestCredentials ? scrubZedCredentials(text, requestCredentials) : redactSecretString(text);
const translated = new Response(zedEventStream(response.body, delegate.provider, scrub), {
status: response.status,
headers: { "Content-Type": "text/event-stream" },
});
try {
// The Responses passthrough parser only keeps compaction text. Zed is not a
// passthrough route, so function and custom calls have to be translated or
// Codex ends the turn on the first sentence.
if (delegate.provider === "open_ai") yield* translateZedOpenAiStream(translated.body, budget);
else yield* delegate.adapter.parseStream(translated, budget);
} finally {
// Some delegates only unlock their reader when a collector stops early.
try { await translated.body?.cancel(); } catch { /* already closed/errored */ }
}
},
async parseResponse(response: Response, budget: TranslatorBudget): Promise<AdapterEvent[]> {
const events: AdapterEvent[] = [];
try {
for await (const event of adapter.parseStream(response, budget)) {
try {
retainTranslatedEvent(event, budget, events.at(-1));
} catch (error) {
releaseCompactionCiphertextLease(event, budget);
throw error;
}
events.push(event);
}
return events;
} catch (error) {
for (const event of events) {
releaseTranslatedEvent(event, budget);
releaseCompactionCiphertextLease(event, budget);
}
throw error;
}
},
};
return adapter;
}