@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
306 lines (286 loc) • 14 kB
text/typescript
/**
* Pure quota-reset detection: two consecutive observations of one usage window in, at most
* one reset event out.
*
* Nothing here reads a clock, a config, or the disk. `now` is a parameter so a test can
* place a deadline in the past without waiting for it, and so the same snapshot pair always
* yields the same answer.
*
* Design and the seven false-positive traps this guards against:
* devlog/_plan/260828_quota_reset_detection/000_plan.md
*/
/** One observed usage window, normalized away from provider-specific field names. */
export type QuotaWindowObservation = {
/** Window identity: "5h", "weekly", "monthly", or "custom:<label>". */
readonly window: string;
/** 0-100 used percent. Absent when upstream stopped reporting this window. */
readonly percent?: number;
/** Epoch ms. Absent when upstream declares no clock, or declared a sentinel. */
readonly resetAt?: number;
/**
* Window length in seconds, when upstream states it.
*
* Used only to bound natural decay in a rolling window (see the surprise branch). Absent
* for providers that never declare a length; the label table then supplies a conservative
* default.
*/
readonly windowSeconds?: number;
/**
* When this observation was taken, stamped by the observer as it stores the baseline.
*
* Needed because a rolling window's percent decays with WALL TIME, so distinguishing decay
* from a reset requires knowing how much time separates the two observations. Absent in
* baselines written before this field existed, and the decay bound is then skipped rather
* than guessed.
*/
readonly observedAt?: number;
};
export type QuotaResetKind = "scheduled" | "surprise";
export type QuotaResetEvent = {
readonly kind: QuotaResetKind;
/** "codex" or a provider name. Never an account identifier. */
readonly scope: string;
/** Non-identifying account discriminator; see quotaAccountTag. */
readonly accountTag: string;
readonly window: string;
readonly percentBefore?: number;
readonly percentAfter?: number;
readonly previousResetAt?: number;
readonly resetAt?: number;
/**
* When WE noticed, not when the reset happened.
*
* Observation cadence is bounded by the 5-minute provider cache TTL and the 10-minute
* per-account TTL, so the reset instant can only ever be bracketed between two
* observations. Naming this field `detectedAt` keeps that limitation visible to every
* consumer instead of implying a precision we do not have.
*/
readonly detectedAt: number;
/** Idempotence key: scope|accountTag|window|resetAt. */
readonly key: string;
};
/**
* A drop smaller than this is rounding noise or a same-window correction, not a reset.
*
* Upstream percents are integers and a real window rollover drops by tens of points, so
* nothing genuine sits under this floor. It applies only to the surprise branch: a
* scheduled rollover is proven by its own expired deadline and needs no magnitude test.
*/
export const MIN_SURPRISE_DROP_PERCENT = 5;
/**
* Account discriminator: stable for this install, unlinkable outside it.
*
* Events must distinguish accounts — a provider report is keyed by provider only, so an
* account switch would otherwise inherit the previous account's history — while carrying no
* account identity, because the payload crosses a webhook boundary to a third party.
*
* The salt is what makes the second half true. An unsalted `Bun.hash` of an email is
* brute-forceable in tens of guesses against a small, highly guessable input space, which
* would let a webhook recipient confirm-or-deny any guessed account. Salted, the tag is
* meaningless to anyone without the install salt, and still stable across restarts because
* the salt is persisted — which is what the durable idempotence key depends on.
*
* Not a cryptographic commitment: it defeats an offline dictionary attack by a payload
* recipient, which is the threat the privacy constraint names.
*/
export function quotaAccountTag(accountKey: string, salt: string): string {
return Bun.hash(`${salt}\u0000${accountKey}`).toString(36).slice(0, 8).padStart(8, "0");
}
export function quotaResetKey(input: {
readonly scope: string;
readonly accountTag: string;
readonly window: string;
readonly resetAt?: number;
readonly previousResetAt?: number;
}): string {
// Prefer the NEW deadline: every later observation of the same post-reset window computes
// the same key, which is what makes repeated detection idempotent.
//
// Fall back to the deadline that just expired when upstream reports no new one. A bare
// "none" discriminator would collapse every clockless reset of one window onto a single
// key, so the first claim would permanently suppress all later ones.
const discriminator = input.resetAt ?? input.previousResetAt ?? "none";
return [input.scope, input.accountTag, input.window, discriminator].join("|");
}
/**
* Percent guard applied at this boundary.
*
* Both upstream normalizers clamp to 0-100, but a value outside that range means the payload
* bypassed them, and admitting a negative would manufacture an enormous apparent drop. Same
* philosophy as the resetAt guard below: re-check rather than trust the caller.
*/
function finitePercent(value: number | undefined): number | undefined {
if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
return value >= 0 && value <= 100 ? value : undefined;
}
/**
* Epoch-ms guard applied at this boundary on purpose.
*
* The two callers normalize differently — src/providers/quota.ts:279 treats <= 0 as a
* sentinel and scales seconds to ms, while src/codex/quota.ts:192 admits 0 and does not
* scale — so the detector cannot trust either and re-checks here.
*/
function finiteResetAt(value: number | undefined): number | undefined {
return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
}
/**
* Decide whether one window transition is a reset.
*
* Returns null for every ambiguous case. The bias is deliberate: a missed notification is
* an inconvenience, while a false one trains the operator to ignore the channel.
*/
export function detectQuotaReset(input: {
readonly scope: string;
readonly accountTag: string;
readonly previous: QuotaWindowObservation | undefined;
readonly next: QuotaWindowObservation;
readonly now: number;
}): QuotaResetEvent | null {
const { scope, accountTag, previous, next, now } = input;
// No baseline, no transition. This one line is what stops a cold start (writers do not
// hydrate from disk), a reauth row clear, a reconciliation delete, and an account switch
// from each manufacturing an event out of thin air.
if (!previous) return null;
if (previous.window !== next.window) return null;
const percentBefore = finitePercent(previous.percent);
const percentAfter = finitePercent(next.percent);
const previousResetAt = finiteResetAt(previous.resetAt);
const resetAt = finiteResetAt(next.resetAt);
const build = (kind: QuotaResetKind): QuotaResetEvent => ({
kind,
scope,
accountTag,
window: next.window,
...(percentBefore !== undefined ? { percentBefore } : {}),
...(percentAfter !== undefined ? { percentAfter } : {}),
...(previousResetAt !== undefined ? { previousResetAt } : {}),
...(resetAt !== undefined ? { resetAt } : {}),
detectedAt: now,
key: quotaResetKey({
scope,
accountTag,
window: next.window,
...(resetAt !== undefined ? { resetAt } : {}),
...(previousResetAt !== undefined ? { previousResetAt } : {}),
}),
});
// A window whose percent vanished says nothing about a reset: upstream simply stopped
// reporting it. Treating absence as 0% would fire on every degraded payload.
if (percentAfter === undefined) return null;
const deadlinePassed = previousResetAt !== undefined && now >= previousResetAt;
if (deadlinePassed) {
if (percentBefore !== undefined && percentAfter > percentBefore) return null;
// An expired deadline alone is NOT enough. src/codex/quota.ts:323-329 carries the
// previous burst tuple forward verbatim when a header write omits it, so a partial
// write reproduces the old deadline and the old percent exactly. Once wall-clock passes
// that copied deadline, "the clock expired" would fire on a snapshot where upstream
// said nothing at all — a false positive on the highest-frequency write path in the
// system (one per pooled response).
//
// Require corroboration that the window actually turned over: either usage fell, or
// upstream issued a new deadline. A byte-identical carried-forward window gives
// neither, so it stays silent.
const usageFell = percentBefore !== undefined && percentAfter < percentBefore;
const deadlineAdvanced = resetAt !== undefined && resetAt > previousResetAt!;
if (!usageFell && !deadlineAdvanced) return null;
return build("scheduled");
}
// Still inside the previous window, so quota coming back means upstream moved the window
// out of band.
//
// A material percent DROP is the only accepted evidence here. An advancing deadline is
// deliberately NOT sufficient, even though it looks like a fresh window: a ROLLING window
// (Anthropic's five_hour, Codex's burst window) reports a deadline that creeps forward on
// every poll by exactly the elapsed time, so "the deadline advanced" is true of every
// healthy observation of a rolling window and would fire continuously.
//
// Nothing is lost by requiring the drop. A surprise reset is worth telling an operator
// about because quota came BACK; if usage did not fall, none did, and there is nothing to
// report. The scheduled branch above can still accept an advancing deadline as evidence,
// because there the previous deadline had genuinely expired.
if (
previousResetAt !== undefined
&& percentBefore !== undefined
&& percentBefore - percentAfter >= MIN_SURPRISE_DROP_PERCENT
&& !isRollingWindowCreep({
previousResetAt,
resetAt,
previousObservedAt: previous.observedAt,
now,
})
) {
return build("surprise");
}
// A window with no deadline on either side is not evaluated. Several provider parsers
// never emit a reset clock at all (credit balances, prepaid pools), and a bare percent
// drop there is as likely to be a top-up or a plan change as a window rollover. Firing on
// it would make the channel noise; the honest answer is that those providers expose no
// window semantics to detect.
return null;
}
/**
* True when the deadline merely CREPT forward with the clock, which is what a rolling window
* does while nothing resets.
*
* A rolling window (Anthropic five_hour, Codex burst) has no rollover instant: usage ages out
* continuously, so its percent falls on its own and its deadline slides forward by roughly the
* elapsed time on every poll. MIN_SURPRISE_DROP_PERCENT only screens integer rounding, so a
* healthy rolling window fired false "surprise" events — measured: 88% -> 61% one hour into a
* 5h window, a 27-point drop with no reset involved.
*
* The discriminator is deadline MOVEMENT against elapsed time, not drop magnitude. Decay
* magnitude cannot be bounded from elapsed time alone, because the percent that ages out
* depends on WHEN the usage happened: an hour of idling can retire a large burst that all
* landed in one minute. Deadline movement behaves differently — while a window is merely
* rolling, its deadline advances by about the elapsed time, whereas a genuine out-of-band
* reset issues a deadline a FULL window into the future, jumping far beyond the elapsed gap.
*
* Fails OPEN (returns false, letting the event through) whenever the evidence is missing: no
* baseline timestamp, no deadline on either side, or a deadline that moved backwards. A
* missed reset is an inconvenience; a suppressed one on an unproven guess is a defect.
*/
function isRollingWindowCreep(input: {
readonly previousResetAt: number | undefined;
readonly resetAt: number | undefined;
readonly previousObservedAt: number | undefined;
readonly now: number;
}): boolean {
const observedAt = finiteResetAt(input.previousObservedAt);
const previousResetAt = input.previousResetAt;
const resetAt = input.resetAt;
if (observedAt === undefined || previousResetAt === undefined || resetAt === undefined) {
return false;
}
const elapsedMs = input.now - observedAt;
if (elapsedMs <= 0) return false;
const deadlineShiftMs = resetAt - previousResetAt;
// A deadline that stood still or moved backwards is not creep. Standing still while usage
// fell is the clearest possible surprise-reset signature, so it must reach the operator.
if (deadlineShiftMs <= 0) return false;
// Creep tracks the clock. The 2x tolerance absorbs polling jitter and upstream rounding to
// whole minutes without approaching a real reset, which shifts the deadline by a whole
// window — hours, against a gap that is minutes on the observation paths that exist here.
return deadlineShiftMs <= elapsedMs * 2;
}
/** Pair two window lists by identity and yield every detected reset. */
export function detectQuotaResets(input: {
readonly scope: string;
readonly accountTag: string;
readonly previous: ReadonlyArray<QuotaWindowObservation>;
readonly next: ReadonlyArray<QuotaWindowObservation>;
readonly now: number;
}): QuotaResetEvent[] {
const before = new Map(input.previous.map(item => [item.window, item]));
const events: QuotaResetEvent[] = [];
for (const observation of input.next) {
const event = detectQuotaReset({
scope: input.scope,
accountTag: input.accountTag,
previous: before.get(observation.window),
next: observation,
now: input.now,
});
if (event) events.push(event);
}
return events;
}