@ycodium-ai/agent-codex 0.2.2690 → 0.2.2694

package/README.md

@@ -26,6 +26,29 @@ Facts:
   key, and the separate shadow directory a second account gets. The UI uses the
   host's React and `@ycodium-ai/plugin-api/provider-settings`.
 
+- Usage (`instance.usage`, ADR-0034), read only when the user asks:
+  - `readQuota` starts a one-shot `codex app-server` on the instance's own
+    account directory and environment (same `maxConcurrentProcesses` limit as a
+    session) and calls `account/rateLimits/read`. Windows are named by
+    `windowDurationMins` (300 session, 10080 weekly, anything else by its
+    duration); the credits balance is a `credits` balance; `planType` is the plan;
+    `rateLimitResetCredits.availableCount` fills `resetCredits`. When the host
+    refuses a new process because the limit is reached, it borrows a live
+    session's app-server for that one request. An instance with its own model
+    endpoint (API URL and key, `-c model_provider=…`, a selected provider that
+    does not point at `chatgpt.com`) reports `customEndpoint` without starting
+    anything; an API-key login reports `unsupportedLogin`.
+  - `redeemQuotaReset` calls `account/rateLimitResetCredit/consume` once with the
+    host's idempotency key unchanged and no credit id, and never retries.
+  - `readTokenUsage` reads `sessions/**` and `archived_sessions/**` under the
+    shared `CODEX_HOME` (a shadow home keeps sessions there too): `last_token_usage`
+    as the increment, cached input split out of `input_tokens`, adjacent repeats
+    skipped, forked history dropped. Per-file results are cached in `ctx.cache`
+    keyed by the account directory, and a growing rollout resumes from its saved
+    byte offset.
+  - `test/codexRateLimitsRead.json` is a redacted real response (codex-cli 0.145.0,
+    Pro plan); the fake CLI answers `account/rateLimits/read` from it.
+
 Develop with `vp run --filter @ycodium-ai/agent-codex typecheck`, `build`, and `test`.
 
 ## License