Skip to content

feat(usage): serve a read-only live meter on GET /v1/usage/live - #8735

Closed
andrew05060414 wants to merge 6 commits into
lidge-jun:devfrom
andrew05060414:feat/live-usage-meter
Closed

andrew05060414 wants to merge 6 commits into
lidge-jun:devfrom
andrew05060414:feat/live-usage-meter

Conversation

@andrew05060414

@andrew05060414 andrew05060414 commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Problem. Users who want generation speed, cache hit and context fill next to the Codex desktop composer currently tail usage.jsonl with a separate reader process and recompute everything from raw ledger rows. OpenCodex already records the exact generation window (genStartMs/lastOutputMs, #6309) and the usage counters, but exposes no small read of "how did the last request go".

After this PR. GET /v1/usage/live returns the newest completed conversation request, overall and per client family, as numbers only:

{ "latest": { "speed": { "value": 90, "reason": null }, "outputTokens": 540, "generationMs": 6000,
    "cache": { "readTokens": 184000, "inputTokens": 200000, "percent": 92, "reason": null },
    "context": { "usedTokens": 200540, "limitTokens": null, "percent": null, "reason": "limit_unknown" },
    "model": "gpt-6.1-sol", "provider": "native", "client": "codex_desktop", "timestamp": 1794612826094 },
  "byClient": { "codex": { "...": "same shape" } }, "generatedAt": 1794613105280 }
  • Never a guess. Speed is reported output tokens over the recorded generation window. It is null with a reason code when the request failed, was cancelled or incomplete, usage is missing or estimated, output tokens are missing, or the window is missing, under 1 s or inconsistent. Cache and context percentages are null with a reason when their inputs are not known; the context limit comes from the persisted Codex catalog's context_window (cached by mtime and size), never a default.
  • Filters. client=codex|claude|other, conversation=<raw id | logged digest | codex://threads/<id>> (reuses matchesLogConversationId). The filter is never echoed. codex-auto-review rows are never reported.
  • Access. Admitted exactly like /v1/models (resolveApiAuth): no credential on a loopback bind, a data key otherwise, never the admin token. Additionally the Codex desktop renderer origin app://- may read this one route and its preflight; the loopback Host gate still applies when no key is required, and every other data-plane route keeps its origin rules (/v1/models from app://- still returns 403). Not reachable over link ingress. No dashboard change.

Details.

  • src/usage/live-meter.ts is the pure projection; src/server/live-meter-handler.ts the route, catalog cache and preflight. serve-options.ts gains two short blocks (now ~1962 of its 2000-line cap). AUTH_MATRIX gains a row. No new imports in src/router.ts, src/server/lifecycle.ts or src/server/responses/core.ts; nothing from src/lab.
  • The preflight answer currently reuses the shared CORS helper, so Access-Control-Allow-Methods lists the generic method set; the route itself only serves GET (POST returns 404).
  • Docs: "Live meter" section in reference/management-api.md (en, es, zh-cn, zh-tw) and structure/usage-client-attribution.md.

Verification

  • tests/usage/live-meter.test.ts (ported generation-window cases plus cache, context and selection) and tests/server/live-meter-handler.test.ts (query validation, client and conversation filters, no id echo, app://- allowed on this route only, non-loopback without key rejected, and a real startServer case): 92 pass across these, core-lab-boundary, management-route-registry, test-layout and the file-size ratchet.
  • Manual check on a local ocx start with synthetic ledger rows: Origin: app://- GET returns 200 with Access-Control-Allow-Origin: app://-; a 6 s window with 540 output tokens reads 90 tok/s; a 0.3 s window reads null / generation_window_too_short; a newer codex-auto-review row in the same conversation is skipped; an unknown conversation returns latest: null; Origin: https://evil.example returns 403.
  • bun run typecheck, bun run structure:check, bun run privacy:scan, Spanish docs localization tests: pass.
  • AUTH_MATRIX is true of the running server times out on this machine with and without this branch (it also fails on a checkout without these commits), so it is left to CI. The real-server case got a 60 s timeout because server start-up under the shared machine's load exceeded the default 5 s.
  • Full bun run test was not run (shared Windows machine; the preload git-config guard rejects GIT_CONFIG_GLOBAL=NUL here). Coverage beyond the files above is left to CI.

Readiness (2026-11-13)

  • Fixed: GET /v1/usage/live was not on the unauthenticated loopback listener's allowlist. On a host whose public listener binds a non-loopback address, the Codex++ footer's 127.0.0.1:<port> read reaches that socket and got a 404. It is now admitted there as GET only. structure/runtime.md and structure/usage-client-attribution.md are updated, and a shape test pins the entry.
  • Verified on a real install with that layout: 404 before, 200 after; a POST is still 404 and /api/* is still 404 there.
  • tests/server/live-meter-handler.test.ts and tests/server/loopback-listener-admission.test.ts: 44 pass.
  • Branch is 2 commit(s) behind dev (873ec9b), inside the gate's window; no rebase for review.
  • No Codex or CodeRabbit findings are open on this PR (CodeRabbit skipped the draft; there are no inline review comments).
  • Also merged into a local integration build with the other open PRs of this series and deployed on a real install. The combined build passed bun run typecheck, structure:check, skill:surface:check, privacy:scan, the layout and file-size guards and this PR's focused tests; after the deploy one real request each through Claude, GPT, Gemini, DeepSeek and Grok returned 200 and the error rate did not rise.
  • Still needs the maintainer-sponsored label: the hygiene gate flags src/server/auth-cors.ts. Everything else is ready for review.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. New read-only data-plane route with the same admission as /v1/models; one extra allowed origin (app://-) scoped to this route; body holds no prompt text, account labels, keys or conversation ids.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

  • Required local validation passed; commands, results, and any full-suite exception are documented.

  • I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

  • I resolved all correct Codex and CodeRabbit findings.

  • My PR is ready for review.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions github-actions Bot added the intake: hygiene-blocked Deterministic PR hygiene checks failed label Nov 14, 2026
@github-actions

Copy link
Copy Markdown
Contributor

⚠️ Deterministic hygiene checks failed.

  • unsponsored_surface — This changes an authentication, workflow, release-automation, or dependency surface. MAINTAINERS.md requires security review for these; ask a maintainer to apply maintainer-sponsored once they have reviewed it. Paths: src/server/auth-cors.ts.

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

⏳ DRAFT

  • hygiene: unsponsored_surface.

What to do

  • Fix unsponsored_surface — This changes an authentication, workflow, release-automation, or dependency surface. MAINTAINERS.md requires security review for these; ask a maintainer to apply maintainer-sponsored once they have reviewed it. Paths: src/server/auth-cors.ts.

Review readiness checklist

  • ✅ Required local validation passed; commands, results, and any full-suite exception are documented.
  • ✅ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
  • ✅ I resolved all correct Codex and CodeRabbit findings.
  • ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request was already a draft. Its draft status will be preserved after every issue above is resolved.

Hygiene

⚠️ Deterministic hygiene checks failed.

  • unsponsored_surface — This changes an authentication, workflow, release-automation, or dependency surface. MAINTAINERS.md requires security review for these; ask a maintainer to apply maintainer-sponsored once they have reviewed it. Paths: src/server/auth-cors.ts.

@github-actions github-actions Bot added the enhancement New feature or request label Nov 14, 2026
@andrew05060414

Copy link
Copy Markdown
Contributor Author

Superseded by #8741, which carries this change together with the related live routing PRs as one commit each on current dev, with no stacking. The design notes in this description still apply.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request intake: hygiene-blocked Deterministic PR hygiene checks failed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant