@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
144 lines (131 loc) • 6.83 kB
text/typescript
/**
* Provider quota shapes, split out of `quota.ts` so a provider-specific quota module can
* describe its result without importing the aggregator that will consume it.
*
* `quota.ts` imports the Kiro usage module for its fetcher; if that module reached back
* into `quota.ts` for these types the two would depend on each other. Types have no
* runtime edge, but a cycle that exists only in the type graph is still a cycle, and it
* blocks any later attempt to load one side without the other.
*/
export const PROVIDER_QUOTA_MAX_AGE_MS = 30 * 60_000;
// Process-local authority: display readings must not acquire key-selection authority.
const displayOnlyQuotas = new WeakSet<ProviderQuota>();
export function markDisplayOnlyQuota(quota: ProviderQuota): ProviderQuota {
displayOnlyQuotas.add(quota);
return quota;
}
export function isDisplayOnlyQuota(quota: ProviderQuota): boolean {
return displayOnlyQuotas.has(quota);
}
/** Management-only eligibility evidence; private credential binding never leaves the server. */
export type ProviderRoutingQuota =
| { state: "unknown" }
| { state: "available" | "exhausted"; updatedAt: number; validUntil: number };
export interface ProviderQuotaWindow {
label: string;
/** Presentation text only; identity and routing use label and structured fields. */
displayLabel?: string;
percent: number;
resetAt?: number;
/**
* Model this window is attributed to: the exact CCA wire model of a fallback measurement, or
* the canonical model of a quota-summary bucket dedicated to one model (Antigravity's Gemini 4
* Argon pool). Display evidence only, never eligibility: routing, exhaustion, reset ordering
* and reset notifications ignore every window that carries it.
*/
modelId?: string;
/**
* Set only when the PRODUCER proved this window covers one model family, structurally rather
* than by reading its label: an Anthropic `seven_day_<family>` body key, or a limit with
* `kind: "weekly_scoped"` and a recognized `scope.model.display_name`.
*
* Absent means provider-wide, which gates every model. That is the fail-closed direction and
* the behaviour every other producer keeps. Routing must key on THIS, never on the label text:
* `quota/antigravity.ts` passes an upstream `group.displayName` straight through, so a
* provider-wide group named "Opus" there would otherwise be mistaken for a per-model window.
*/
scope?: "model";
/**
* Share of the provider-wide weekly limit a model-scoped window may consume, in percent:
* Anthropic's `weekly_scoped_shares[].allowance_percent_of_weekly` (Fable is "up to 50% of
* your weekly limit"). `percent` stays relative to this allowance. Read from upstream, never
* inferred from a plan; ranking restates family usage on the weekly scale with it.
*/
weeklyAllowancePercent?: number;
/** Passive family readings have their own freshness clock, independent of active probes. */
passiveObservedAt?: number;
/** Upstream refusal evidence, distinct from a measured utilization counter. */
rejected?: true;
}
export interface ProviderQuotaCreditsUsd {
used: number;
limit: number;
remaining: number;
percent: number;
expiresAt?: number;
unlimited?: boolean;
}
export interface ProviderQuota {
/** Display-only budget windows for which the upstream did not provide a usable entitlement. */
unknownBudgetWindows?: { label: string; resetAt?: number }[];
/** Claude CLI extra-usage entitlement/cap only; enabled does not prove wallet funds. */
claudeExtraUsage?: "enabled" | "disabled" | "exhausted";
/** Display-only subscription credits; not a routing or exhaustion window. */
workbuddyCredits?: import("./workbuddy-credit-balance").WorkBuddyCreditBalance;
fiveHourPercent?: number;
fiveHourResetAt?: number;
weeklyPercent?: number;
weeklyResetAt?: number;
monthlyPercent?: number;
monthlyResetAt?: number;
/** Observed Kiro plan credits, independent of token and currency estimates. */
kiroCreditsUsed?: number;
kiroCreditsLimit?: number;
customWindows?: ProviderQuotaWindow[];
/**
* Display-only measurements the producer withheld from routing: Anthropic model-scoped rows
* that upstream reports with `is_active: false`. Routing, exhaustion, cooldown recovery and
* reset ordering read only `customWindows`; nothing but quota display reads this field.
*/
displayWindows?: ProviderQuotaWindow[];
creditsUsd?: ProviderQuotaCreditsUsd;
updatedAt: number;
}
export type AccountQuotaMode = "probe" | "passive" | "unsupported";
/** Additive management-row fields; cheap lists emit only quotaMode. */
export interface AccountQuotaFields {
quotaMode?: AccountQuotaMode;
quota?: ProviderQuota | null;
quotaUnavailable?: boolean;
quotaFailure?: QuotaFailureCode;
/** Why the current balance is unknown (#8397); a last-good value may still ride along with read_failed. */
quotaUnknownReason?: QuotaUnknownReason;
/** When the balance was last read (epoch ms), success or failure; absent when never read. */
quotaReadAt?: number;
}
/**
* Closed reasons a balance is unknown. A row with a reason must never be rendered as zero.
* no_balance_source: no reader exists for this destination. passive_not_observed: a passive
* provider has not observed usage yet. read_failed: a reader exists and its last read failed.
* not_read: a reader exists but no read was made (paused key, or the key changed mid-read).
* not_reported: the read succeeded and the provider authoritatively reported no balance to meter
* (for example zero total credits, or a plan with no model window).
*/
export const QUOTA_UNKNOWN_REASONS = ["no_balance_source", "passive_not_observed", "read_failed", "not_read", "not_reported"] as const;
export type QuotaUnknownReason = typeof QUOTA_UNKNOWN_REASONS[number];
export function parseQuotaUnknownReason(value: unknown): QuotaUnknownReason | undefined {
return QUOTA_UNKNOWN_REASONS.find(reason => reason === value);
}
/** Closed account-probe diagnoses; never upstream text, URLs, credentials or routing policy. */
export const QUOTA_FAILURE_CODES = [
"account_unavailable", "access_denied", "rate_limited", "upstream_error", "redirect_blocked",
"destination_blocked", "dns_failed", "timeout", "transport_error", "response_unusable",
] as const;
export type QuotaFailureCode = typeof QUOTA_FAILURE_CODES[number];
export function parseQuotaFailureCode(value: unknown): QuotaFailureCode | undefined {
return QUOTA_FAILURE_CODES.find(code => code === value);
}
/** A model family's share of the weekly limit is meaningful only as a finite percent in (0, 100]. */
export function isWeeklyAllowancePercent(value: unknown): value is number {
return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100;
}