UNPKG

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