@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
245 lines (227 loc) • 10.9 kB
text/typescript
/**
* One vocabulary for how far a failed request got, why it failed, and whether this proxy may
* send it again (roadmap items 7 and 14).
*
* These two items are one module on purpose. Item 7 wants a resend decision per failure stage;
* item 14 wants one cause dictionary spanning logical request, attempt, physical send and
* terminal. Defined apart they typecheck on each branch and contradict each other in the merge,
* which is the class that blocked 2.60.0.
*
* What lives here is the vocabulary and the decision derived from it. What does NOT live here is
* a second record store: the durable shapes stay `PersistedUsageAttempt` and
* `PersistedUsageEntry` in src/usage/log.ts, and every projection below reads those structurally
* rather than growing a parallel history.
*
* MUST stay a leaf. Its one runtime import is `src/usage/telemetry-contract.ts`, which has no
* imports at all; everything else it names is a type, erased at runtime. So nothing here can
* pull the usage or budget subsystems into a request path that did not already have them.
*/
import type { SendClass } from "./request-execution-budget";
import {
REQUEST_FAILURE_STAGES,
type AttemptRecoveryKind,
type RequestFailureCause,
type RequestFailureStage,
type ResendPermission,
} from "../usage/telemetry-contract";
/**
* The vocabulary this module decides over is DECLARED in `src/usage/telemetry-contract.ts` and
* re-exported here, so every importer of this module keeps its path while the dashboard can
* reach the same rosters without pulling this file's import graph into the browser project.
*
* What stays here is the decision: the per-stage commitment, the per-cause evidence and
* disposition, and the resend permission derived from them.
*
* A stage is how far the OBSERVABLE progression got, not which events happened to arrive. A turn
* that settled carrying no output -- an empty completion, a 4xx error body -- did not reach
* `terminal`; it stalled below `semantic-output`, because the caller saw no answer. `terminal`
* means the answer was delivered, which is why it is both last and refused.
*/
export {
REQUEST_FAILURE_CAUSES,
REQUEST_FAILURE_STAGES,
RESEND_PERMISSIONS,
} from "../usage/telemetry-contract";
export type {
RequestFailureCause,
RequestFailureStage,
ResendPermission,
} from "../usage/telemetry-contract";
/** Position in {@link REQUEST_FAILURE_STAGES}. Derived, so the order is stated exactly once. */
export function stageRank(stage: RequestFailureStage): number {
return REQUEST_FAILURE_STAGES.indexOf(stage);
}
/**
* What the caller has irreversibly observed at a stage.
*
* Named separately from the rank so a reader can see WHY a stage refuses rather than inferring it
* from a position, and so the three committed stages stay distinguishable in a record.
*/
export type StageCommitment = "nothing-observed" | "output-observed" | "effect-observed" | "answer-delivered";
const STAGE_COMMITMENT = {
"pre-header": "nothing-observed",
"headers-only": "nothing-observed",
"protocol-prelude": "nothing-observed",
"semantic-output": "output-observed",
"side-effect": "effect-observed",
"terminal": "answer-delivered",
} as const satisfies Record<RequestFailureStage, StageCommitment>;
export function stageCommitment(stage: RequestFailureStage): StageCommitment {
return STAGE_COMMITMENT[stage];
}
/**
* What the cause proves about whether the origin ran the turn.
*
* This is the safety axis. `unknown` is the RFC 9110 9.2.2 case and is never upgraded by having
* budget left: a request whose upstream execution state is unknown is not replayable merely
* because a counter allows another send.
*/
export type UpstreamProcessingEvidence = "not-processed" | "declined" | "processed" | "unknown";
const CAUSE_EVIDENCE = {
"transport-unsent": "not-processed",
"transport-ambiguous": "unknown",
"upstream-declined": "declined",
"rate-limit": "declined",
"quota-exhausted": "declined",
"credential-rejected": "declined",
"policy-refusal": "processed",
"parameter-rejected": "declined",
"ciphertext-refusal": "declined",
"payload-too-large": "declined",
"payload-rejected": "declined",
"upstream-fault": "unknown",
"empty-output": "processed",
"client-cancelled": "unknown",
"local-refusal": "not-processed",
} as const satisfies Record<RequestFailureCause, UpstreamProcessingEvidence>;
export function causeEvidence(cause: RequestFailureCause): UpstreamProcessingEvidence {
return CAUSE_EVIDENCE[cause];
}
/**
* What a resend would have to change to have any chance.
*
* The usefulness axis, orthogonal to safety. A policy refusal is perfectly safe to repeat and
* completely pointless; an ambiguous reset is the reverse.
*/
export type ResendDisposition = "resend-may-help" | "resend-after-repair" | "resend-is-futile";
const CAUSE_DISPOSITION = {
"transport-unsent": "resend-may-help",
"transport-ambiguous": "resend-may-help",
"upstream-declined": "resend-may-help",
"rate-limit": "resend-may-help",
"quota-exhausted": "resend-is-futile",
"credential-rejected": "resend-after-repair",
"policy-refusal": "resend-is-futile",
"parameter-rejected": "resend-after-repair",
"ciphertext-refusal": "resend-after-repair",
"payload-too-large": "resend-after-repair",
"payload-rejected": "resend-is-futile",
"upstream-fault": "resend-may-help",
"empty-output": "resend-may-help",
"client-cancelled": "resend-is-futile",
"local-refusal": "resend-is-futile",
} as const satisfies Record<RequestFailureCause, ResendDisposition>;
export function causeDisposition(cause: RequestFailureCause): ResendDisposition {
return CAUSE_DISPOSITION[cause];
}
/**
* Whether this proxy may send the request again, from the stage it failed at and the cause.
*
* Derived from the two per-cause facts above and the per-stage commitment, rather than written
* out as a stage-by-cause matrix. A matrix of that size is a restatement: it would have to be
* re-derived by hand every time a member is added, and the cell nobody revisited is exactly how
* two correct branches merge into a wrong table.
*
* `refused-ambiguous` forbids an AUTOMATIC resend. It does not forbid a narrowly scoped,
* explicitly opted-in recovery that a maintainer reasoned about and bounded -- the reset replay
* behind a default-off provider flag, the single-shot empty-completion rebuild. Those are
* separate recorded decisions with their own acceptance, which is precisely what distinguishes
* them from a retry loop that fires because a counter had room.
*/
export function resendPermission(
stage: RequestFailureStage,
cause: RequestFailureCause,
): ResendPermission {
// Any stage at which the caller observed something refuses, whatever the cause says. Testing
// the commitment rather than listing the committed stages is what keeps a stage added later
// from defaulting into permission.
if (STAGE_COMMITMENT[stage] !== "nothing-observed") return "refused-committed";
if (CAUSE_DISPOSITION[cause] === "resend-is-futile") return "refused-futile";
const evidence = CAUSE_EVIDENCE[cause];
if (evidence === "unknown" || evidence === "processed") return "refused-ambiguous";
return CAUSE_DISPOSITION[cause] === "resend-after-repair" ? "permitted-after-repair" : "permitted";
}
/** True for the two permissions that allow a further send. */
export function permitsResend(permission: ResendPermission): boolean {
return permission === "permitted" || permission === "permitted-after-repair";
}
/**
* Which request-wide send budget class a resend for this cause draws on, or null when no resend
* of any kind makes sense.
*
* Funding is keyed on the DISPOSITION, not on the permission. A cause the table refuses to resend
* automatically may still be resent by a narrowly scoped recovery a maintainer opted into, and
* that send has to be bought from the same budget every other send comes from -- the opt-in reset
* replay and the bounded empty-completion rebuild both draw on the transient allowance. Keying on
* permission instead would leave exactly those paths unfunded, which is how a per-layer counter
* reappears.
*
* Only a futile cause is null. `quota-exhausted` is null rather than `account-failover` because
* moving accounts is a route decision this table does not make.
*/
const CAUSE_SEND_CLASS = {
"transport-unsent": "transient",
"transport-ambiguous": "transient",
"upstream-declined": "transient",
"rate-limit": "transient",
"quota-exhausted": null,
"credential-rejected": "auth-recovery",
"policy-refusal": null,
"parameter-rejected": "repair",
"ciphertext-refusal": "repair",
"payload-too-large": "repair",
"payload-rejected": null,
"upstream-fault": "transient",
"empty-output": "transient",
"client-cancelled": null,
"local-refusal": null,
} as const satisfies Record<RequestFailureCause, SendClass | null>;
export function resendSendClass(cause: RequestFailureCause): SendClass | null {
return CAUSE_SEND_CLASS[cause];
}
/**
* The cause behind each recovery this proxy already records.
*
* Total over `AttemptRecoveryKind` by construction, so a new recovery kind is a typecheck
* failure here rather than a row that quietly classifies as "other" in three projections.
*/
const RECOVERY_KIND_CAUSE = {
// The retried status set mixes 503, which declined, with 500, which may already have run the
// turn. One kind cannot say both, so it says the weaker thing.
"transient-5xx": "upstream-fault",
"connection-reset": "transport-ambiguous",
// The send it replaced failed DNS resolution, so those bytes provably never left (#7958).
"offline-resend": "transport-unsent",
"oauth-401": "credential-rejected",
"oauth-account-403": "credential-rejected",
"key-401": "credential-rejected",
"key-429": "rate-limit",
"rate-limit-429": "rate-limit",
"anthropic-oauth-429": "rate-limit",
"oauth-account-429": "rate-limit",
// A 402 is the account's quota, not a transient limit; only another account can serve it.
"oauth-account-402": "quota-exhausted",
"image-413": "payload-too-large",
// The gateway rejects a body it accepts seconds later and the replay is byte-identical, so
// nothing about the payload was wrong; the origin declined to take it at that moment.
"console-go-upload-retry": "upstream-declined",
"opaque-blob-rejection": "ciphertext-refusal",
"empty-completion": "empty-output",
"reasoning-effort-downgrade": "parameter-rejected",
// Anthropic refused `speed: "fast"` (no usage credits, org not enabled, model outside the
// lane); the same turn succeeds once the parameter is dropped.
"anthropic-fast-downgrade": "parameter-rejected",
} as const satisfies Record<AttemptRecoveryKind, RequestFailureCause>;
export function causeForRecoveryKind(kind: AttemptRecoveryKind): RequestFailureCause {
return RECOVERY_KIND_CAUSE[kind];
}