quota-axi: Instructions file for Codex

Project agent memory

This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.

• VISION.md is the project's acceptance policy, co-authored with the repo owner against 17 recorded hypothetical verdicts; check a proposed surface against its closing aligns/resisted tests before building it. It deliberately sits ahead of today's implementation in places: accuracy of the reported number is the first obligation, and boundaries such as read-only and never-launch hold as "least action that yields a true reading" rather than as absolutes. README Security Posture remains the description of what actually ships today; do not restate VISION.md wording as a current guarantee.
• quota-axi is data only.
• It reports local Claude, Codex, Cursor, GitHub Copilot, Grok, Kimi, Z.AI, Alibaba, OpenCode Go, and Antigravity (agy) quota windows, and it must never route, recommend, rank a winner, order providers preferentially, proxy, intercept, log in, import browser cookies, or mint/rotate a credential.
• Delegated credential refresh is the one carve-out and it is shared machinery in src/providers/delegated-refresh.ts: a delegate is eligible only when the same stored access token is expired, carries a refresh token, and was definitively rejected; quota-axi may then run the vendor CLI's own smallest non-interactive rotation command and re-read the store that CLI rewrote. quota-axi must never perform a refresh-token exchange itself (these tokens rotate on use; a second exchange signs the user out of the harness being measured), and the delegated-refresh machinery must never read a refresh token's value - presence only. quota-axi also never signals a delegated run: the budget bounds only how long quota-axi waits, the child runs in its own process group (Ctrl+C on a live --tui must not reach it), and a run that outruns the budget resolves as unconfirmed/refresh_timed_out - reported as unmeasured or stale, never as a sign-out, and never retiring the cache. Claude adds a best-effort safety check on top: before delegating, src/lib/running-processes.ts must report no Claude Code process, because Claude Code owns that session's refresh. This also prevents a later read from stacking another refresh on a timed-out claude doctor that is still running. An unlistable process table stays read-only. The check and spawn are not atomic, so a Claude Code session starting after the check or another concurrent quota-axi read can still overlap the delegate. This narrows the common repeated five-minute --tui versus live-session collision and, together with never signaling the delegate, is strictly safer than force-killing without adding a failure mode beyond the pre-existing vendor-owned race. Tests mock that module so the machine's real process table never decides a test. Contract, per-provider delegates, and the read-only providers are documented in README Delegated credential refresh; route any new provider's delegate through that module rather than spawning ad hoc.
• A provider gets a delegate only when that command's rotation behavior is established empirically from the vendor's own CLI. Today: Claude claude doctor, Grok grok models, and Codex's existing app-server probe. Cursor, Copilot, Kimi, Z.AI, Alibaba, OpenCode Go, Antigravity, and Pi-owned entries stay read-only; leaving a provider read-only is always allowed, forcing an unsafe or interactive path never is.
• Data-only reconciliation: quota-axi does publish one derived per-scope comparative selection signal (effectiveAvailability[].selection), computed purely from figures it already reports. That is data, not routing - the consumer does any routing or ranking. Keep this distinction in src/skill.ts frontmatter/identity wording and README wording; never claim quota-axi recommends or ranks.
• The shipped skill stays MINIMAL and DEFERS to the CLI for all actual guidance. src/skill.ts generates skills/quota-axi/SKILL.md as a stub: identity/discovery frontmatter, what quota-axi is, when to reach for it, and pointers to npx -y quota-axi (default TOON), --help, and --json / --full. quota-axi CLI output is the single source of truth; never re-duplicate CLI-owned instructions into the skill. Prefer a pointer over restated detail.
• Claude quota windows can include five_hour, seven_day, seven_day_opus, and extra_usage. When the OAuth usage response includes a limits array, that array is the authoritative, self-describing source and is preferred over the fixed top-level fields: it surfaces every active limit, including ones scoped to a specific model (e.g. Fable) via scope.model.display_name, with a model:<slug> window id.
• Claude credential-validity and cache-fallback contracts are documented in README Security Posture.
• Codex window identity and cache-validation contracts are documented in README Provider windows and README Cache.
• An inherited bound is only as good as the evidence that the vendor enforces it. availability() in src/interpretation.ts takes an optional own-windows argument; when every window metered for a scope alone still reports allowance while an inherited window reads zero, it publishes effectiveAvailability[].boundConflict and leaves the scope unknown instead of asserting exhausted_now/effective 0. That is disclosure, not the opposite assertion: one successful call proves the inherited bound was unenforced at that moment, not that it never binds. Codex passes its named model windows because the vendor ships them as separately metered additional_rate_limits/rateLimitsByLimitId budgets and a zeroed base weekly was observed alongside live, drawing-down model windows; Claude, Grok, and Alibaba keep their established account bounds and must not be opted in without the same empirical evidence. Contract in README Quota windows and the bound_conflict row in README Default report blocks.
• Cursor's editor source reads $CURSOR_STATE_DB or the local Cursor state database via sqlite3 -readonly for cursorAuth values and can report included_usage, auto_usage, api_usage, and optional spend_limit windows from GetCurrentPeriodUsage, plus an optional grok_bot weekly window from GetSandUsageStatus on the same first-party dashboard service. Grok Bot is a separate Cursor-account meter: keep it off the IDE all_models bound, and do not call trial, banked-reset, or machine-registration RPCs.
• Cursor's quota-interpretation contract, including Grok Bot's separate grok_bot scope and unfamiliar windows, is documented in README Quota windows.
• Cursor's monthly pools reset on the subscription renewal date, so src/providers/cursor.ts sets each monthly window's startsAt from a reported billingCycleStart or, failing that, from billingCycleEnd stepped back one calendar month (clamped to the shorter month). Never substitute a fixed 30-day duration, and leave the cycle unresolved when neither field is present.
• If sqlite3 is unavailable, Cursor auth is reported as skipped with sqlite3_unavailable; do not treat that as permission to install system packages.
• Cursor has two independent, additive credential sources: the editor state-vscdb store and the Cursor CLI (cursor-agent) source in src/providers/cursor-cli-credential.ts. macOS uses the cli-keychain source; Linux uses the cli-authfile source and reads only accessToken from $CURSOR_CLI_CONFIG or the XDG cursor/auth.json path. Either source alone supports auth inspection and quota refresh, so Cursor Desktop is not required. Keep the editor source first, preserve the existing Keychain prompt gate, never read refreshToken or cursor-refresh-token, and do not invent credential refresh. Attempt naming, credential locations, and recovery behavior are documented in README Provider notes.
• GitHub Copilot reads $GITHUB_COPILOT_APPS_JSON or the local github-copilot/apps.json auth file and can report quota snapshot windows such as chat, completions, and premium_interactions from GitHub's first-party Copilot user endpoint. If the endpoint only exposes entitlement and no numeric quota windows, return a fresh provider report with windows: [] rather than inventing percentages.
• Copilot only sends tokens associated with public GitHub hosts to the public endpoint; host-specific GitHub Enterprise tokens are treated as unavailable there.
• Grok reads two independent usability sources: Grok CLI session auth ($GROK_AUTH_JSON, inline $GROK_AUTH, $GROK_AUTH_PATH, or $GROK_HOME/auth.json/~/.grok/auth.json) and Pi's $PI_CODING_AGENT_DIR/auth.json xai entry (default ~/.pi/agent/auth.json, OAuth or literal API key). Treat Grok as usable when either source is locally usable; true sign-out requires every applicable source unavailable or rejected.
• Grok CLI path selects session-scoped auth instead of API-key entries and recognizes official Grok Build OIDC records scoped to auth.x.ai with auth_mode or authMode set to oidc.
• Grok consumer credits are fetched read-only from grok_api_v2.GrokBuildBilling.GetGrokCreditsConfig using the Grok CLI session bearer and/or Pi xai OAuth (same endpoint; never refresh or write). That consumer operation can reject an otherwise live official Build/Pi OAuth audience: on auth rejection only, probe the matching no-spend model catalog (cli-chat-proxy.grok.com/v1/models for Build, api.x.ai/v1/models for Pi), discard its body, and report authStatus: usable with empty windows instead of false sign-out. Never derive quota from model presence. A Pi API key likewise only establishes usable, unmeasurable model auth. The grok remedy requires the same refreshable CLI bearer to be rejected by both surfaces. Soft CLI/Pi expiry is authStatus: expired_refreshable, not auth_required logout.
• Multi-source providers report the source that works: a broken store must never speak for a provider whose sibling store still answers. Sources are consulted in priority order and handover happens on credential problems only, never on transport/decoding/server failures (those belong to the request, not the credential). The superseded source stays visible: src/lib/source-attempts.ts classifies attempts (status: "failed", or skipped with credentialPresent; a provider sets degraded: false on a non-credential attempt such as Grok's live model probe or Claude's oauth-profile), withQuotaSemantics in src/interpretation.ts publishes state.degradedSources on fresh readings only, and src/render.ts emits the degraded_source attention row. Contract in README Default report blocks and README Provider state.
• Credential selection is shared machinery in src/providers/credential-selection.ts: stored expiry is advisory only within one source, never a verdict or a reason to reorder declared sources. Stored-expired credentials are empirically tested in that source's fixed position before any expired/sign-in verdict, an empirically live credential always wins, and transient failures never switch candidates within one source or become auth verdicts. Independent Grok CLI and Pi sources may still be tried in turn. New or migrated provider adapters must route multi-credential selection through this module instead of skipping expired-by-stored-field credentials; Claude's advisory-expiry loop is the semantic precedent. Grok, Codex, and Kimi route through it; Codex and Kimi call it once per source so each provider's ownership-stability order stays authoritative. A broker's expired resolution therefore carries the stored token (probe use only, never logged or rendered) so the adapter can test it.
• Provider and credential-source onboarding checklist:
  1. Enumerate every source in an ownership-stability order declared by a named constant. Keep absent, structurally_invalid, unsupported, read_error, and resolved (stored-valid or stored-expired) distinct at the typed local-resolution boundary; route Pi entries through classifyPiAuthEntry in src/lib/pi-auth-store.ts, and derive credentialPresent once from that resolution rather than at each call site.
  2. Separate local resolution from the bounded read-only liveness probe. Enroll stored-expired credentials instead of skipping them, never infer liveness from presence, and classify probe outcomes as usable, live_no_quota, definitively_rejected, or transient; only a first-party 401/403 is an auth verdict.
  3. Handover only after definitive credential failure. An absent source is never degraded; a present-but-broken source superseded by a working sibling is degraded on fresh readings only; stale means last-known cache. Inspect refresh-token presence only, and never read or exchange its value.
  4. Add adapter regressions for primary healthy, stored-expired plus live sibling, structurally invalid present, absent source, all rejected, refreshable expired, and transient stops handover; extend the cross-provider invariant table in test/credential-contract.test.ts.
• Grok credential recovery and quota interpretation contracts are documented in README Provider state, README Provider windows, and README Security Posture.
• Grok cache fallback accepts only current web source snapshots, not legacy api billing-proxy entries. Never send cookies, launch Pi, exchange a refresh token, or retain raw responses; the only Grok process quota-axi starts is the declared grok models refresh delegate.
• Codex OAuth credential availability is access-token authoritative: expired id_token alone must not mark auth-json expired or skip the bearer quota probe.
• Kimi's credential, fallback, and transport contracts are documented in README Security Posture. Pi's kimi-coding entry is read in place as either an api_key or an oauth access token; absent files or entries resolve as missing, malformed stores or entries as invalid, unknown types as unsupported, and expired OAuth as expired, which carries the stored token so it is probed in Pi's fixed source position before falling through to the Kimi Code CLI source. It is never refreshed, mirroring src/providers/pi-xai-credential.ts. All Pi auth readers route their provider-entry boundary through src/lib/pi-auth-store.ts, so only an absent file or provider property is missing; a present non-object entry is invalid.
• Z.AI (zai) reads the Coding Plan API key from opencode's auth.json (zai-coding-plan entry, plus zai/z-ai/z.ai → api.z.ai and zhipu/zhipuai → open.bigmodel.cn), XDG path first, and sends it bare (no Bearer) in one GET to /api/monitor/usage/quota/limit per refresh. The endpoint is undocumented (only the vendor's own plugin/console depend on it), so the normalizer is schema-tolerant: TOKENS_LIMIT windows are distinguished only by unit/number magic numbers (3/5 → five_hour, 6/1 → weekly) — map by those, never by array position; TIME_LIMIT → mcp_month; unrecognized limits, and repeats of an already reported one, degrade to untrusted kind:"unknown" windows named in state.untrustedWindowIds. The key is accepted only through the usableLiteralSecret guard in src/lib/secret.ts (the pi-*-credential.ts readers still carry equivalent private copies; route new adapters through the shared module), and zaiSemantics keeps the token windows' all_models bound and the mcp_month tools bound separate in both its known and partial branches. Attribution to opencode-glm-quota (MIT) lives in src/providers/zai.ts.
• Antigravity (agy) is a default unscoped provider in PROVIDER_IDS. Discovery, loopback transport, and quota contracts are documented in README Provider windows and README Security Posture. It never launches Antigravity/agy, invents windows/resets/percentages, or contacts unowned ports.
• Process-table discovery (agy loopback endpoints and the Claude delegated-refresh safety check) shells out to ps through currentUserProcessListArgs in src/lib/process.ts, which is platform-specific because Linux procps rejects the BSD -x selector alongside -u. Route any new process-table read through that helper rather than spelling the flags again.
• Provider adapter behavior (retry-after handling, snake/camel field tolerance, window parsing) is an original, clean-room implementation derived only from the vendors' own OAuth/HTTP behavior; quota-axi carries no vendored third-party adapter code. The Z.AI adapter is the single attribution exception (derived from opencode-glm-quota, MIT), credited in src/providers/zai.ts; no third-party code is copied. Claude, Codex, Copilot, Cursor, and Grok route their remote HTTP calls through src/lib/http.ts so standard upper/lowercase HTTP(S) proxy and NO_PROXY environment policy is applied consistently without logging proxy URLs; route new remote fetches through it rather than global fetch.
• ProviderOptions.refreshCredentials gates delegated refresh. --no-credential-refresh turns it off; the read-only auth command always passes false. Tests must pass it explicitly so no test can spawn a vendor CLI by accident.
• Slow-path CLI plumbing (routing, --help, trailing version flags, error framing, exit codes, and the built-in update self-updater) comes from axi-sdk-js runAxiCli, matching sibling tasks-axi; machine TOON/JSON rendering stays in src/render.ts and the command bodies live in src/commands.ts.
• bin/quota-axi.ts answers a bare -v/-V/--version through axi-sdk-js/fast-path plus the leaf src/version.ts (node builtins only), and imports src/cli.js dynamically so the provider graph never loads on that path. Keep src/version.ts leaf-clean; test/version-fast-path.test.ts guards this with an ESM loader module trace (plus negative control) and flag parity, deliberately with no wall-clock CI assertion.
• quota is the implicit default command: runAxiCli routes on argv[0] and rejects a leading flag, so src/cli.ts normalizeArgv prepends quota for a bare call or flag-first call (quota-axi --json) while leaving auth, update, single-token --help, and any version flag that reaches the slow path to the SDK. Validation errors throw AxiError("...", "VALIDATION_ERROR") (exit 2); the all-providers-failed path sets process.exitCode = 1 and still renders.
• Default stdout is compact TOON, restructured into three decision-shaped blocks: quota[] (one fully populated row per measurable scope), sparse exhaustion[] (finite-runway measurable scopes only, joined on provider + scope), and sparse attention[] (every non-nominal fact). Its two contract invariants - every requested provider appears in quota[] or attention[], and quota[] rows stay in provider-declaration order and are never metric-sorted - are documented in README Default report blocks and covered by test/cli.test.ts. spendPriority renders the literal unknown, never 0; an unknown or stale scope gets no quota[] row, and any finite-runway verdict for it is preserved in attention[] with the limiting window. Provider attention details preserve state.reason.
• --json emits the normalized model with derivation inputs demoted to --full, with no renames and no re-nesting; --full also adds account identity and per-source attempts. The tier split is documented in README Output tiers. Demote at the renderer/serialiser only, never at computation: src/render.ts quotaJsonReport builds the --json payload, renderQuotaToon builds TOON, and the in-memory model keeps every field so --tui and --full are unaffected.
• There is deliberately no projectionBasis field anywhere: every projection is cycle-average, and its absence means cycle_average. There is no selection[] TOON block either - the scalar is already the quota[] row's spendPriority column.
• --tui (quota command only, mutually exclusive with --json) renders the human card-grid report from the pure renderer in src/tui.ts, driven on an interactive terminal by the injected-io live loop in src/tui-live.ts (--refresh, --once, q/Ctrl+C to quit); it is presentation only, documented in README Human terminal report, and must never change the TOON/JSON machine contract, exit codes, or caching.
• renderQuotaTui is deliberately height-independent: it lays cards out for the width and returns however many lines that takes. The alternate screen has no scrollback, so the live loop must never paint more physical rows than the terminal has - src/tui-viewport.ts scrollFrame windows the frame using terminal display widths, pins the first line, clips oversized lines, and reserves the last row for the scroll affordance when height permits; content wins those rows in tinier terminals. src/tui-live.ts owns the offset and scroll keys. Keep the closing hint out of renderQuotaTui (compose it with renderTuiHintLine + scrollHint), and keep the live paint free of a trailing newline so a frame that exactly fills the terminal does not scroll itself.
• TUI wording is humanized independently of the machine contract: through_reset renders as on pace ✓, pace is shown only by the bar fill and ┃ marker (no burn-multiple chip or legend), and projected exhaustion is a relative empty in Nd Nh headline countdown (no triangle prefix, warning styling retained) with no absolute-time body note. JSON and TOON keep through_reset; the complete pace object remains in the in-memory model and --full --json. The headline bar uses the binding window's own label from limitingWindowIds (week/session/credits) as its primary label; scoped rollups may append their model or product scope. A provider with wholly unknown window relationships drops the headline percent, verdict, and bar for a single per-window usage · no combined bound line instead of rendering an empty track. See README Human terminal report.
• JSON report shape and quota interpretation, including stale effective availability, per-window cycle-average pace, effective usable runway, and the per-scope selection signal (schemaVersion: 5), are documented in README Output Model, README Pace signals, README Effective usable runway, and README Per-scope selection signal. Pace, runway, and selection are derived in src/pace.ts from trusted startsAt/resetsAt or windowSeconds plus generatedAt; runway aggregates every authoritative bound, preserves uncertainty, and is not cached. Negative reservePercentPoints means usage is ahead of the reset clock. state.retryAfter can appear for provider rate limits, and state.reason: keychain_access_required plus state.remedyCommand can appear when a stale or unavailable Claude or Cursor result is blocked by a skipped macOS Keychain prompt.
• summarizeEffectiveSelection in src/pace.ts is the selection scalar's only implementation, and SELECTION_SCALAR_KEY in src/types.ts is the single place its published field name is spelled. Any bounding window without usable pace makes the whole scope unmeasurable (no scalar, unmeasurableWindowIds named); an unknown window is never assumed healthy or defaulted to zero. worstReservePercentPoints stays the non-routing single-window diagnostic and must not be conflated with it.
• macOS Claude Keychain presence and value reads mirror Claude Code's validated current-user account selector and never fall back to an ambiguous service-only query. Value reads are skipped on plain calls until a successful value read records the profile-and-account-scoped non-secret access marker under the quota-axi cache directory; after that, plain calls may reuse the existing grant and read live Claude quota. security exit 44 is cannot-reach (keychain_unreachable), not signed-out, and must not retire the Claude cache. Offer --allow-keychain-prompt only for keychain_prompt_required; denied/timeout Keychain outcomes must still appear as errors. A stale usage-fetch failure names fetch failed plus the actual error in attention[].
• Managed-profile, Claude identity, and Codex credential-source, refresh-ownership, and executable-override contracts are documented in README Security Posture.
• --allow-keychain-prompt is the first-time opt-in that permits Claude or Cursor CLI Keychain value reads which can prompt, and agents should relay the one-time "Always Allow" grant when keychain_access_required advice appears.
• Codex uses $CODEX_HOME/auth.json or ~/.codex/auth.json OAuth, then Pi's openai-codex entry, before the CLI fallback. A higher-priority source's real failure is never overwritten by a lower-priority one's credential diagnostic.
• Codex auth.json support is OAuth-token only; never treat OPENAI_API_KEY as valid quota auth or send API keys to ChatGPT quota endpoints.
• Never launch the Claude CLI to probe quota, because that would spend the quota being measured. claude doctor is permitted only as the delegated refresh: it starts no session, sends no model request, and does not connect to MCP servers (unlike claude mcp list, which does and is therefore not the delegate).
• The read-only Alibaba bl usage command and Codex app-server JSON-RPC probe are the CLI quota fallbacks; the Codex probe also doubles as Codex's delegated refresh.
• The cache path is ~/.cache/quota-axi/quotas.json, or under $XDG_CACHE_HOME/quota-axi/ when XDG_CACHE_HOME is set.
• The Claude Keychain access marker is stored alongside the cache, is 0600, is keyed by hashed profile/account identity, and contains no credential material or raw account name. Legacy service-only markers are ignored without being deleted.
• Quota cache files must be 0600 and contain only normalized non-secret snapshots.
• Only fresh provider snapshots with windows are cached; fresh provider reports with no windows clear any existing cached snapshot for that provider. Claude snapshots additionally carry an opaque SHA-256 selected-configuration context identifier, and stale fallback rejects legacy or mismatched contexts.
• Failed providers, stale providers, account identity, source attempts, and derived pace objects are not cached.
• Do not cache raw provider responses or credential headers.