@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
202 lines (195 loc) • 10.7 kB
text/typescript
import type { OcxProviderConfig } from "../types";
import { CODEX_RESPONSES_LITE_HEADER, mergeCodexSelectedHeaders } from "../codex/forward-transport-headers";
import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
import { redactSecretString } from "../lib/redact";
import { sidecarEnter } from "../lib/sidecar-tracker";
import {
applyUpstreamRecoveryInit,
fetchWithResetRetry,
releaseResponseBodyBestEffort,
retryBackoffDelayMs,
sleepWithAbort,
RETRY_AFTER_CEILING_MS,
} from "../lib/upstream-retry";
import { withUpstreamHttpVersion } from "../lib/upstream-http-version";
import { parseSidecarSSE, type WebSearchResult } from "./parse";
import type { CodexUpstreamOutcome } from "../codex/routing";
import { NATIVE_RESERVE_MODEL } from "../codex/catalog/native-models";
import { openAiSidecarCreditRefusal } from "../providers/openai-sidecar-credit";
export interface SidecarSettings {
model: string;
reasoning: string;
timeoutMs: number;
/** Effective Desktop authless compatibility does not grant auxiliary model use. */
reserveCompatibility?: boolean;
/**
* True when the routed (downstream) model is text-only. The search model CAN see images, so it's
* told to verbalize any relevant image results and include their URLs — otherwise a non-vision model
* would receive bare image links it cannot interpret (the image-web-search gap).
*/
describeImages?: boolean;
}
// Shared with the anthropic-backed executor (single source; audit F3). The instruction is
// backend-agnostic — both the gpt-mini sidecar and a Claude sidecar answer the same way.
export const BASE_INSTRUCTION =
"You are a web-search assistant. Use the web_search tool to find current information for the " +
"user's query, then reply with a concise, factual answer. End your reply with a `Sources:` " +
"section listing each source you used on its own line as `- Title: URL` (one per line).";
export const IMAGE_INSTRUCTION =
" The model that will read your answer is TEXT-ONLY and cannot see images: if the results include " +
"relevant images, describe what they show in words and include their source URLs in your answer.";
/** A search result, or an `error` string when the search couldn't run (surfaced as a tool result). */
export type SidecarOutcome = WebSearchResult & { error?: string };
/**
* Bounded same-search 429 replays for the sidecar POST.
*
* The forward backend throttles burst sidecar traffic, and without a replay the 429 becomes a
* failed tool result that poisons the query for the whole turn (see failedQueries in loop.ts).
* 1 initial send + 2 replays, counted as physical sends: connection-reset recovery inside each
* send draws from the same SIDECAR_MAX_SENDS budget, so the two layers cannot multiply into nine
* paid requests during a degraded period. Retry-After is honored as a lower bound and capped by
* RETRY_AFTER_CEILING_MS and the remaining sidecar deadline (an instruction past either
* ends with the 429 instead of parking the search). Each wait releases the unread 429 body first so sockets do not
* accumulate under a rate-limit storm. The release itself may take up to a second, so a
* deadline landing during release or backoff ends with the 429 already in hand rather than
* a timeout; a caller abort still ends the wait through the shared catch, exactly like an
* abort during the SSE parse. An exhausted budget likewise ends with the 429 in hand.
*/
const SIDECAR_MAX_SENDS = 3;
const SIDECAR_429_BASE_DELAY_MS = 1_000;
const SIDECAR_429_MAX_DELAY_MS = 10_000;
export type SidecarOutcomeRecorder = (outcome: CodexUpstreamOutcome) => void;
/**
* Execute ONE web search via the gpt-mini sidecar through the ChatGPT forward backend — the only path
* with a real server-side web_search. Reuses selected forwarded OAuth headers (the forward adapter
* has no key of its own), replays the hosted web_search tool config verbatim, and runs the mini at
* minimal reasoning. Never throws — returns `{error}` so the caller injects a graceful tool result.
*/
export async function runWebSearch(
query: string,
hostedTool: Record<string, unknown>,
forwardProvider: OcxProviderConfig,
selectedForwardHeaders: Headers,
settings: SidecarSettings,
abortSignal?: AbortSignal,
recordOutcome?: SidecarOutcomeRecorder,
beforeDispatch?: () => void,
): Promise<SidecarOutcome> {
if (settings.reserveCompatibility && settings.model === NATIVE_RESERVE_MODEL) {
return { text: "", sources: [], error: "Luna Reserve compatibility is only available as a conversation model, not a search helper. Choose another search helper model." };
}
const mergedHeaders = mergeCodexSelectedHeaders(
{ "Content-Type": "application/json", ...forwardProvider.headers }, selectedForwardHeaders,
);
mergedHeaders.delete(CODEX_RESPONSES_LITE_HEADER);
const headers = Object.fromEntries(mergedHeaders);
const body = {
model: settings.model,
instructions: settings.describeImages ? BASE_INSTRUCTION + IMAGE_INSTRUCTION : BASE_INSTRUCTION,
input: [{ type: "message", role: "user", content: [{ type: "input_text", text: query }] }],
tools: [hostedTool],
tool_choice: "auto",
reasoning: { effort: settings.reasoning },
// NOTE: the ChatGPT (codex) backend rejects `max_output_tokens` ("Unsupported parameter") and
// requires `store: false` — keep this body minimal. The shared SSE parser bounds raw response
// bytes before format-result applies its smaller display clamp.
store: false,
stream: true,
};
const url = `${forwardProvider.baseUrl}/responses`;
// t0 precedes the deadline timer's start so the remaining-time check stays conservative.
const t0 = Date.now();
const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
const sidecarExit = sidecarEnter("web-search");
try {
// One physical-send budget for the whole search. Each helper call receives only what is left
// and reports every send it makes, reset retries included.
let sendsLeft = SIDECAR_MAX_SENDS;
const sendOnce = () => fetchWithResetRetry(
// Recovery nests INSIDE the version helper: applyUpstreamRecoveryInit then always receives a
// defined init, and withUpstreamHttpVersion spreads the result, so `protocol` and the
// recovery fields (`connection: close` + Bun's transport-level `keepalive: false`) survive
// together. The reverse order needs a `?? init` fallback to type-check at all.
recovery => {
beforeDispatch?.();
return fetch(url, withUpstreamHttpVersion(url, applyUpstreamRecoveryInit({
method: "POST",
headers,
body: JSON.stringify(body),
signal: linkedSignal.signal,
// Credential-bearing: do not follow a cross-origin 3xx. Bun strips `Authorization`
// across origins but forwards nonstandard headers such as `chatgpt-account-id`,
// `session_id`, and `x-codex-turn-metadata` to the redirect target.
redirect: "manual",
}, recovery), forwardProvider));
},
{
replaySafe: true,
abortSignal: linkedSignal.signal,
label: "web-search-sidecar",
attempts: sendsLeft,
onSendsConsumed: sends => { sendsLeft -= sends; },
},
);
let res = await sendOnce();
// Checked before the 429 body is released: a budget found spent after the release could only
// end in a send-budget error, recorded as a connection failure instead of the quota evidence.
for (let attempt = 0; res.status === 429 && sendsLeft > 0; attempt++) {
const delay = retryBackoffDelayMs(attempt, {
baseDelayMs: SIDECAR_429_BASE_DELAY_MS,
maxDelayMs: SIDECAR_429_MAX_DELAY_MS,
headers: res.headers,
retryAfterIsLowerBound: true,
});
// A deadline, not a clamp: an instruction past the ceiling ends the search with the
// 429 instead of parking it at a provider that already said it would refuse.
if (delay > RETRY_AFTER_CEILING_MS || delay >= settings.timeoutMs - (Date.now() - t0)) break;
console.warn(`[web-search] sidecar HTTP 429 — retrying (send ${SIDECAR_MAX_SENDS - sendsLeft + 1}/${SIDECAR_MAX_SENDS}) after ${delay}ms`);
try {
await releaseResponseBodyBestEffort(res.body, linkedSignal.signal);
await sleepWithAbort(delay, linkedSignal.signal);
} catch (e) {
// The release above may consume up to 1s, so the sidecar deadline can land during
// cleanup or mid-backoff — before the replay is dispatched. The observed 429 is
// already in hand: end with it rather than laundering it into a timeout. A caller
// abort (or a non-deadline throw) still propagates to the shared catch below.
if (!linkedSignal.signal.aborted || linkedSignal.signal.reason === abortSignal?.reason) throw e;
break;
}
res = await sendOnce();
}
// Attach the body guard before ANY branch reads it. The success path guarded itself below,
// but the failure branch's `res.text()` runs first, so a cancel landing between fetch
// resolution and reader attach orphaned the internal rejection (found investigating #1419).
const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
if (!res.ok) {
recordOutcome?.(res.status);
const t = await res.text().catch(() => "");
detachBodyGuard();
console.warn(`[web-search] sidecar HTTP ${res.status} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
return { text: "", sources: [], error: `sidecar HTTP ${res.status}: ${redactSecretString(t.slice(0, 200))}` };
}
try {
const parsed = await parseSidecarSSE(res);
if (linkedSignal.signal.aborted) throw linkedSignal.signal.reason;
recordOutcome?.(res.status);
return parsed;
} finally {
detachBodyGuard();
}
} catch (e) {
const policyRefusal = openAiSidecarCreditRefusal(e);
if (policyRefusal) return { text: "", sources: [], error: policyRefusal.message };
const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
const callerAborted = abortSignal?.aborted === true
&& linkedSignal.signal.aborted
&& linkedSignal.signal.reason === abortSignal.reason
&& e === linkedSignal.signal.reason;
recordOutcome?.(callerAborted ? "connect_neutral" : kind);
console.warn(`[web-search] sidecar ${kind} for query "${query.slice(0, 80)}" (${Date.now() - t0}ms)`);
return { text: "", sources: [], error: e instanceof Error ? e.message : String(e) };
} finally {
sidecarExit();
linkedSignal.cleanup();
}
}