@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
185 lines (176 loc) • 10.3 kB
text/typescript
/**
* Derive how far a failed request got and why, from the closed facts the recorder already holds.
*
* #2366 asked for durable failure attribution and shipped its own `FailureSide` and seven-member
* `FailureStage` to carry it. Those are a second attribution vocabulary beside the one that
* landed in {@link ../lib/request-failure-model}, and two vocabularies for one question is the
* class of defect that blocked 2.60.0. This module is the same answer expressed in the landed
* vocabulary: no new stage names, no new cause names, and no new record store.
*
* Everything it reads is a CLOSED value the row already carries -- an HTTP status, a terminal
* status, a close reason, a transport phase, a recovery kind. It never reads `errorCode` or
* `upstreamError`, which are open strings assembled partly from upstream text: a classification
* keyed on those is a different answer per provider and per locale, and a grouping key built from
* them cannot promise it carries no content.
*
* MUST stay a leaf. Its only imports are types and the two tables it decides with, so nothing
* here can pull the usage or budget subsystems into a request path that lacked them.
*/
import type { AttemptRecoveryKind, RequestFailureCause, RequestFailureStage } from "../usage/telemetry-contract";
import { causeForRecoveryKind } from "./request-failure-model";
import { classifyRequestOutcome, type RequestOutcomeFacts } from "../usage/request-outcome";
/**
* What the recorder knows about one finished exchange at the single seam every request passes.
*
* Deliberately the same narrow set {@link RequestOutcomeFacts} reads, plus the four observation
* facts a stage needs. A field that could carry a provider name, a model, an account or upstream
* text is absent by construction rather than by review.
*/
export interface RequestFailureFacts extends RequestOutcomeFacts {
readonly transportPhase?: "pre_headers" | "mid_stream" | "terminal_sse" | undefined;
/** Where the status and message came from: an origin response, or a tail this proxy wrote. */
readonly terminalSource?: "upstream" | "synthetic" | undefined;
/** True when the upstream stream died after its head was committed. */
readonly streamAborted?: boolean | undefined;
/** True once any output-bearing event reached the caller; `firstOutputMs` is the usual source. */
readonly outputObserved?: boolean | undefined;
/** True once a tool call or other externally visible effect was relayed to the caller. */
readonly sideEffectObserved?: boolean | undefined;
/** True when this proxy answered the turn itself and issued no upstream request. */
readonly locallyAnswered?: boolean | undefined;
/**
* Recovery kinds recorded on the attempt that ended the request, in the order they happened.
* Only the LAST one is ever consulted, and only under the narrow rule below.
*/
readonly recoveryKinds?: readonly AttemptRecoveryKind[] | undefined;
/**
* A cause the CALLER proved, which the status alone cannot reconstruct.
*
* Set only by a finalizer that is sealing an attempt it knows the rejection for -- the
* key-account rotation seals the previous attempt because a named recovery rejected it, and
* that argument is direct evidence rather than an inference from history. It outranks the
* status table and is outranked by a client cancel, which is a fact about the caller and not
* about the origin.
*/
readonly causeHint?: RequestFailureCause | undefined;
}
/**
* How far the caller's view of the exchange got.
*
* Total by construction and ordered downward from the most committed observation, so a fact that
* proves a later stage wins over one that only proves an earlier one. The boundary between
* `headers-only` and `protocol-prelude` is the one genuinely debatable step -- a non-streaming
* 4xx error body is a body, but not a protocol body event -- and it is safe to argue about
* because both stages carry the same `nothing-observed` commitment, so no resend decision turns
* on which side of it a row lands.
*/
export function deriveRequestFailureStage(facts: RequestFailureFacts): RequestFailureStage {
if (facts.terminalStatus === "completed" && facts.outputObserved === true) return "terminal";
if (facts.sideEffectObserved === true) return "side-effect";
if (facts.outputObserved === true) return "semantic-output";
if (facts.terminalStatus !== undefined
|| facts.closeReason === "terminal"
|| facts.transportPhase === "mid_stream"
|| facts.transportPhase === "terminal_sse") return "protocol-prelude";
if (facts.status >= 100) return "headers-only";
return "pre-header";
}
/**
* The two recovery kinds that name a 4xx the status alone cannot tell apart.
*
* `causeForRecoveryKind` answers why a recovery was ATTEMPTED, which is usually a different
* question from why the request finally failed -- one that recovered from a 401 and then died on
* a 500 failed for the 500. So the rule here is deliberately narrow on three axes at once: only
* these two kinds, only when they are the LAST recovery this attempt recorded, and only when the
* attempt then ended on the very status that recovery was made for. Everything else falls
* through to the status table.
*
* The residual: a ciphertext recovery that SUCCEEDED, followed by an unrelated 400 on the same
* attempt, still reads as `ciphertext-refusal`, because a successful recovery does not currently
* clear its own evidence. Closing that belongs in the recovery path rather than here -- it is
* recorded in this lane's devlog as the next step -- and the rule is kept meanwhile because
* without it a rejected ciphertext, a rejected reasoning parameter and a rejected payload are one
* undifferentiated answer, which is three different remedies collapsed into one.
*/
const STATUS_CONFIRMED_RECOVERY_KINDS: Readonly<Partial<Record<AttemptRecoveryKind, number>>> = Object.freeze({
"opaque-blob-rejection": 400,
"reasoning-effort-downgrade": 400,
"anthropic-fast-downgrade": 400,
});
function refinedFourHundredCause(
facts: RequestFailureFacts,
): RequestFailureCause | undefined {
const last = facts.recoveryKinds?.at(-1);
if (last === undefined) return undefined;
const confirmedStatus = STATUS_CONFIRMED_RECOVERY_KINDS[last];
return confirmedStatus === facts.status ? causeForRecoveryKind(last) : undefined;
}
/**
* Why the request failed.
*
* Returns `undefined` for an outcome that is not a failure. An incomplete turn is a real
* shortfall and gets a stage, but this dictionary answers "why did it fail", and a turn cut short
* by `max_output_tokens` did not fail for any of these reasons; inventing one would put a
* fabricated cause into a metric label and a grouping key.
*
* The status is the primary evidence because it is the one fact every transport produces. Two
* refinements sit above it, both from closed values: a client cancel is known from the close
* reason before any status is consulted, and a 400 that a recovery kind identified as a rejected
* ciphertext or a rejected reasoning parameter is not the same answer as a rejected payload.
*/
export function deriveRequestFailureCause(facts: RequestFailureFacts): RequestFailureCause | undefined {
const outcome = classifyRequestOutcome(facts);
if (outcome === "completed" || outcome === "incomplete") return undefined;
if (outcome === "aborted") return "client-cancelled";
if (facts.locallyAnswered === true) return "local-refusal";
// A cause the finalizer proved outranks anything reconstructed from the status.
if (facts.causeHint !== undefined) return facts.causeHint;
const status = facts.status;
// Transport evidence outranks the numeric status, because a stream that died mid-flight is
// reported as a SYNTHETIC 502 -- a tail this proxy wrote, not an answer the origin gave. Read
// in status order that 502 becomes `upstream-fault`, which claims the origin answered when it
// did not. Both causes refuse an automatic resend, so this is an accuracy fix rather than a
// safety one, but a label an operator cannot trust is a label they stop reading.
if (facts.streamAborted === true
|| (facts.terminalSource === "synthetic"
&& (facts.transportPhase === "mid_stream" || facts.transportPhase === "terminal_sse"))) {
return "transport-ambiguous";
}
// A 2xx head that carried a failed terminal: the origin ran the turn and said it failed. With
// no output relayed the useful distinction is that nothing usable came back at all.
if (status >= 100 && status < 400) {
return facts.outputObserved === true ? "upstream-fault" : "empty-output";
}
if (status === 401) return "credential-rejected";
if (status === 403) return "credential-rejected";
// Payment required. Waiting out a retry window does not help; the account has to change.
if (status === 402) return "quota-exhausted";
if (status === 413) return "payload-too-large";
if (status === 429) return "rate-limit";
if (status === 451) return "policy-refusal";
if (status === 503) return "upstream-declined";
if (status >= 500) return "upstream-fault";
if (status >= 400) return refinedFourHundredCause(facts) ?? "payload-rejected";
// No response head at all, and nothing proved the bytes never left. `transport-ambiguous` is
// the honest answer for an unknown execution state, and it is the safe one: it refuses an
// automatic resend where `transport-unsent` would permit one. `transport-unsent` is reachable
// only through `causeHint`, from a site that classified a pre-connect failure and can prove it.
return "transport-ambiguous";
}
export interface RequestFailureAttribution {
stage: RequestFailureStage;
cause?: RequestFailureCause;
}
/**
* The attribution to persist, or `undefined` when the request completed.
*
* A completed request has no failure to attribute, and recording a stage for one would put a
* `terminal` row into every grouping that exists to find failures.
*/
export function deriveRequestFailureAttribution(
facts: RequestFailureFacts,
): RequestFailureAttribution | undefined {
if (classifyRequestOutcome(facts) === "completed") return undefined;
const cause = deriveRequestFailureCause(facts);
return { stage: deriveRequestFailureStage(facts), ...(cause ? { cause } : {}) };
}