@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
140 lines (132 loc) • 6.67 kB
text/typescript
/**
* Whether one leg of a logical request may send it again, asked in the #5266 vocabulary.
*
* Two pull requests arrived at this question from opposite sides of the response head. #4942
* asked it for a connection that died before any head; #4989 asked it for an SSE body that
* died after the head while carrying only control events. Both are the same row of the stage
* table: a stage the caller observed nothing at, with a cause that cannot prove the origin did
* not run the turn. A Codex WebSocket that dies under its create frame before any Responses
* event (#4191) is that row a third time. `resendPermission` answers `refused-ambiguous` for all
* of them, and request-failure-model.ts already names the only thing that may override that
* answer -- a narrowly scoped recovery a maintainer opted into and bounded.
*
* One override, not two. The reason this module exists rather than a boolean in each caller is
* that a request which resets before the head and again after it would otherwise buy a
* replacement send on each side, and the second one is exactly the duplicated inference the
* refusal exists to prevent. The allowance is claimed HERE, at the moment of authorisation, so
* a caller cannot ask without paying.
*
* MUST stay a leaf. It imports the vocabulary as values and everything else as types, so it
* reaches no request path that did not already have it.
*/
import {
causeForRecoveryKind,
permitsResend,
resendPermission,
resendSendClass,
type RequestFailureCause,
type RequestFailureStage,
type ResendPermission,
} from "./request-failure-model";
import type { SendClass } from "./request-execution-budget";
import type { AttemptRecoveryKind } from "../usage/telemetry-contract";
/**
* Why an authorisation was refused.
*
* The three ambiguous members are separate because they need different operator responses: no
* policy is a configuration choice, a request the proxy cannot judge is a property of the turn,
* and a spent allowance means the replacement already went somewhere else in this request.
*/
export const RESEND_REFUSALS = Object.freeze([
/** The caller already observed output, an effect, or the delivered answer. */
"committed",
/** Identical bytes would get the identical answer. */
"futile",
/** The origin's execution state is unknown and no operator policy overrides that. */
"ambiguous-no-policy",
/** An operator policy exists, but this request's second send could do more than re-infer. */
"ambiguous-request-not-replayable",
/** The operator policy exists and its replacement was already spent by this request. */
"ambiguous-allowance-spent",
] as const);
export type ResendRefusal = typeof RESEND_REFUSALS[number];
/**
* The operator-granted replacement for ONE logical request.
*
* `claim` is the single counter both stages draw on. It is a method rather than a number
* because the holder is the request's send ledger, which a combo child shares with its parent;
* a number passed down per leg is what let each leg hold its own.
*/
export interface AmbiguousResendAllowance {
/** True when a second send of this request's body can only repeat the inference. */
readonly selfContained: boolean;
/** Spend one replacement. False once the request has none left. */
claim(): boolean;
}
interface ResendDecisionBase {
readonly stage: RequestFailureStage;
readonly cause: RequestFailureCause;
readonly permission: ResendPermission;
/**
* The recovery this send will be recorded as, when the caller asked in those terms. Carried
* back rather than re-chosen at the call site: the cause was derived from it, so recording a
* different kind would describe the send by a reason the gate never evaluated.
*/
readonly recoveryKind?: AttemptRecoveryKind;
}
export type ResendDecision =
| ResendDecisionBase & {
readonly allowed: true;
/** Which request-wide send class funds it, or null when the cause funds no resend. */
readonly sendClass: SendClass | null;
/** True when the table refused and an operator allowance was spent to proceed. */
readonly spentOperatorAllowance: boolean;
}
| ResendDecisionBase & { readonly allowed: false; readonly refusal: ResendRefusal };
/**
* Decide whether this proxy may send the request again after a failure at `stage` caused by
* `cause`, spending `allowance` when the table refuses only because the upstream state is
* unknown.
*
* The allowance is touched on exactly one path: a decision the table would otherwise refuse as
* ambiguous, for a request whose body the caller has judged replayable. A committed or futile
* failure never reaches it, so a turn that already produced output cannot quietly drain the
* replacement a later ambiguous reset would have been entitled to.
*/
export function authorizeResend(
stage: RequestFailureStage,
cause: RequestFailureCause,
allowance?: AmbiguousResendAllowance,
recoveryKind?: AttemptRecoveryKind,
): ResendDecision {
const permission = resendPermission(stage, cause);
const base = { stage, cause, permission, ...(recoveryKind ? { recoveryKind } : {}) };
if (permitsResend(permission)) {
return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: false };
}
if (permission === "refused-committed") return { ...base, allowed: false, refusal: "committed" };
if (permission === "refused-futile") return { ...base, allowed: false, refusal: "futile" };
if (!allowance) return { ...base, allowed: false, refusal: "ambiguous-no-policy" };
if (!allowance.selfContained) {
return { ...base, allowed: false, refusal: "ambiguous-request-not-replayable" };
}
// Claimed last, and only here. Asking earlier would spend the request's one replacement on a
// question whose answer was already no.
if (!allowance.claim()) return { ...base, allowed: false, refusal: "ambiguous-allowance-spent" };
return { ...base, allowed: true, sendClass: resendSendClass(cause), spentOperatorAllowance: true };
}
/**
* The same decision, asked in terms of the recovery this proxy will RECORD for the send.
*
* Deriving the cause from the recorded kind is what keeps the log honest: the reason an
* operator reads beside a send count is the reason the gate weighed, because it is the same
* value. A call site that recorded one kind and reasoned about another is how a send count
* stops meaning anything.
*/
export function authorizeResendForRecovery(
stage: RequestFailureStage,
kind: AttemptRecoveryKind,
allowance?: AmbiguousResendAllowance,
): ResendDecision {
return authorizeResend(stage, causeForRecoveryKind(kind), allowance, kind);
}