UNPKG

@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
/** * 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); }