@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
207 lines (189 loc) • 10.7 kB
text/typescript
import { upstreamValidationIssues, type ValidationIssue } from "../lib/upstream-validation-detail";
import { isDeveloperRoleRejection } from "../lib/developer-role-rejection";
import { clientFacingModelText, errorDestinationText, providerErrorDestinationLabel } from "../lib/error-destination";
import { knownModelIdentity } from "../lib/model-identity";
/**
* Proxy-authored failure detail for request logs.
*
* Some transports describe a failure themselves (header timeout, body stall, byte cap, client close,
* a restated upstream status and closed error type). The row keeps a closed FailureDetail code with
* bounded parameters (src/lib/failure-detail.ts); the English text goes only into the context's
* upstreamError, which internal classifiers and status heuristics read and which never reaches a row.
* Only proxy-composed text may be passed here.
*/
import { boundedFailureDetail, providerErrorTypeOf, providerFailureDetailOf, type FailureDetail, type FailureDetailCode } from "../lib/failure-detail";
export type { FailureDetail };
export const FAILURE_DETAIL_MAX_LENGTH = 500;
/** Contexts whose upstreamError currently holds proxy text rather than upstream evidence. */
const localOnly = new WeakSet<object>();
/**
* Pass `upstreamEvidence: true` only when the text restates an upstream response (its status and a
* closed type); a local timeout, cap or cancel is not evidence of an upstream condition.
*/
export function recordLocalFailureDetail(
logCtx: { upstreamError?: string; failureDetail?: FailureDetail },
text: string,
detail: FailureDetail,
options: { upstreamEvidence?: boolean } = {},
): void {
// The classifier and status heuristics keep reading upstreamError; the row keeps the closed detail.
logCtx.upstreamError = text.slice(0, FAILURE_DETAIL_MAX_LENGTH);
logCtx.failureDetail = detail;
if (options.upstreamEvidence) localOnly.delete(logCtx);
else localOnly.add(logCtx);
}
/** True when the context's upstreamError is proxy text; the final row then carries no upstream evidence. */
export function upstreamErrorIsLocal(logCtx: object): boolean {
return localOnly.has(logCtx);
}
/** One attempt's local verdict on a reused context: the proxy-text mark and the detail recorded with it. */
export interface LocalFailureState { local: boolean; detail?: FailureDetail }
/**
* End an attempt on a context the next attempt reuses: drop its local verdict so the next attempt's
* upstream evidence counts again. Returns the verdict so a rolled-back attempt can restore it.
*/
export function takeLocalFailureState(logCtx: { failureDetail?: FailureDetail }): LocalFailureState {
if (!localOnly.delete(logCtx)) return { local: false };
const detail = logCtx.failureDetail;
delete logCtx.failureDetail;
return detail ? { local: true, detail } : { local: true };
}
/** Put back the verdict a rolled-back attempt replaced; a non-local verdict only clears the mark. */
export function restoreLocalFailureState(logCtx: { failureDetail?: FailureDetail }, state: LocalFailureState): void {
if (!state.local) {
localOnly.delete(logCtx);
return;
}
localOnly.add(logCtx);
if (state.detail) logCtx.failureDetail = state.detail;
}
/** Carry a selected attempt's local verdict across request-log contexts. */
export function carryLocalFailureState(
source: { upstreamError?: string; failureDetail?: FailureDetail },
target: { upstreamError?: string; failureDetail?: FailureDetail },
): void {
const local = upstreamErrorIsLocal(source);
restoreLocalFailureState(target, { local, detail: source.failureDetail });
if (local) target.upstreamError = source.upstreamError;
}
const INCOMPLETE_REASONS: Readonly<Record<string, readonly [string, FailureDetailCode]>> = {
max_output_tokens: ["Output reached the requested token limit (max_output_tokens)", "output_limit"],
upstream_stall_timeout: ["Upstream stalled: no data for the stall-timeout window (upstream_stall_timeout)", "stall_timeout"],
adapter_eof: ["Upstream stream ended unexpectedly without a terminal event (adapter_eof)", "adapter_eof"],
};
/**
* A structured `incomplete_details.reason` (emitted by the bridge on a stall timeout or adapter EOF):
* the context text that explains it, and a closed detail for a known reason.
*/
export function incompleteReasonDetail(reason: string): { text: string; detail?: FailureDetail } {
const known = Object.prototype.hasOwnProperty.call(INCOMPLETE_REASONS, reason) ? INCOMPLETE_REASONS[reason] : undefined;
return known ? { text: known[0], detail: { code: known[1] } } : { text: `Upstream incomplete: ${reason}` };
}
/** Local model refusals keep only client or catalog identities in the request row. */
export function projectLocalModelRefusalLog(
logCtx: import("./request-log").RequestLogContext,
clientModel: import("../lib/error-destination").ClientFacingModelLabel,
): void {
const client = clientFacingModelText(clientModel);
const known = (value: unknown) => knownModelIdentity(value, [client]);
const providerKnown = (value: string) => errorDestinationText(providerErrorDestinationLabel(value)) === value;
if (logCtx.provider && !providerKnown(logCtx.provider)) logCtx.provider = "unknown";
logCtx.model = known(logCtx.model) ?? "unknown";
logCtx.requestedModel = known(logCtx.requestedModel);
logCtx.requestedAlias = known(logCtx.requestedAlias);
logCtx.wireModel = known(logCtx.wireModel); logCtx.resolvedModel = known(logCtx.resolvedModel);
logCtx.servedModel = known(logCtx.servedModel); logCtx.responseModelEcho = known(logCtx.responseModelEcho);
for (const attempt of logCtx.attempts ?? []) {
attempt.model = known(attempt.model) ?? "unknown";
if (!providerKnown(attempt.provider)) attempt.provider = "unknown";
}
const decision = logCtx.routeDecision;
if (decision && (!known(decision.requestedModel)
|| decision.candidates.some(candidate => !known(candidate.model) || !providerKnown(candidate.provider))
|| decision.selected && (!known(decision.selected.model) || !providerKnown(decision.selected.provider)))) logCtx.routeDecision = undefined;
}
const isRecord = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
/**
* The closed pair a developer-role rejection records (#8864); the dashboard already renders it. A fresh
* array per row, because a valid list is stored by reference and must not be shared between rows.
*/
const developerRoleValidation = (): ValidationIssue[] => [{ field: "messages.role", type: "enum" }];
/**
* Capture bounded schema facts before a 4xx is replaced by the client-facing error policy. Only a caller
* holding the provider's own body sets `providerBody`, which also reads its message once for a
* developer-role rejection; a body this proxy formatted keeps validation-only capture.
*/
export function recordUpstreamValidationDetail(
logCtx: { failureDetail?: FailureDetail }, status: number, payload: unknown, options: { providerBody?: boolean } = {},
): void {
if (status < 400 || status >= 500) return;
let parsed = payload;
if (typeof payload === "string") {
if (payload.length > 256 * 1024) return;
try { parsed = JSON.parse(payload); } catch { return; }
}
const record = isRecord(parsed) ? parsed : undefined;
const nested = record && isRecord(record.error) ? record.error : undefined;
const message = typeof nested?.message === "string" ? nested.message
: typeof record?.message === "string" ? record.message : typeof record?.error === "string" ? record.error : undefined;
// Read once to choose the closed pair; the message itself is dropped here.
const validation = upstreamValidationIssues(parsed)
?? (options.providerBody && isDeveloperRoleRejection(status, message) ? developerRoleValidation() : undefined);
if (!validation) return;
logCtx.failureDetail = boundedFailureDetail({ code: "provider_error", type: nested?.type ?? record?.type, validation });
}
/**
* Capture the closed provider error class from a raw upstream error body (#8446): the envelope
* `type` (Anthropic/OpenAI) or Google's `error.status`, the latter also as the first element of a
* streamed JSON array. Validation pairs keep their existing capture and win when present. Only
* callers holding the provider's own body may use this; a body this proxy formatted is not evidence.
* An adapter transport that rewrote the body (normalizeUpstreamHttpErrorResponse) attached the class
* it read from the original to `response`, which is preferred.
*/
export function recordUpstreamProviderErrorDetail(
logCtx: { failureDetail?: FailureDetail },
status: number,
payload: unknown,
response?: object,
): void {
if (status < 400 || status >= 600) return;
const before = logCtx.failureDetail;
recordUpstreamValidationDetail(logCtx, status, payload, { providerBody: true });
if (logCtx.failureDetail !== before) { providerDetails.set(logCtx, logCtx.failureDetail!); return; }
let type = response ? providerFailureDetailOf(response)?.type : undefined;
if (type === undefined) {
let parsed = payload;
if (typeof payload === "string") {
if (payload.length > 256 * 1024) return;
try { parsed = JSON.parse(payload); } catch { return; }
}
type = providerErrorTypeOf(parsed);
}
if (type === undefined) return;
const detail: FailureDetail = { code: "provider_error", type };
logCtx.failureDetail = detail;
providerDetails.set(logCtx, detail);
}
/** The provider detail each context last recorded, so a later success can retract exactly that one. */
const providerDetails = new WeakMap<object, FailureDetail>();
/**
* Request-log side of every adapter event (the parse seam in request-transport.ts). An error event an
* adapter tagged with closed provider facts records them as a provider_error detail; a later `done` on
* the same request (a retry or replay that succeeded) retracts a detail this path recorded, so a
* successful row never names a provider failure it recovered from.
*/
export function observeProviderFailureEvent(logCtx: { failureDetail?: FailureDetail }, event: { type: string }): void {
if (event.type === "done") {
const recorded = providerDetails.get(logCtx);
if (recorded !== undefined && logCtx.failureDetail === recorded) delete logCtx.failureDetail;
providerDetails.delete(logCtx);
return;
}
if (event.type !== "error") return;
const facts = providerFailureDetailOf(event);
if (!facts) return;
const detail = boundedFailureDetail({ code: "provider_error", ...facts });
if (!detail) return;
logCtx.failureDetail = detail;
providerDetails.set(logCtx, detail);
}