Expose rate limits on usage updates

[s-cork]

Fork-only draft for review. This does not submit or retarget anything in agentclientprotocol/codex-acp.

Summary

• attach stored Codex rate-limit snapshots to ACP usage_update events under _meta["_codex/rateLimits"]
• emit a refreshed usage update when rate limits change and context usage is already known
• retain rate limits received before token usage and include them in the next usage update
• merge sparse rolling updates with known values, including updates that omit an ID or name
• preserve existing usage updates when no rate-limit snapshot is available

Rationale

codex-acp already stores account rate-limit snapshots for status reporting, but ACP clients cannot consume them. Namespaced metadata exposes the same snapshots without changing the standard ACP usage fields.

Rate-limit notifications are sparse: nullable fields mean unavailable, not cleared. Merging them with the last known snapshot prevents rolling updates from erasing windows, credits, plan metadata, or spend-control state.

The main review points are the extension shape, event timing, sparse-update merging, and accumulation of multiple independently identified rate limits.

Testing

• focused token-usage suite — 9 passed
• npm run typecheck
• npm test — 331 passed, 28 skipped
• npm run bundle:all with Bun 1.3.11
• git diff --check main...HEAD

Tests cover deferred emission when a rate-limit notification arrives first, immediate refresh after usage is known, and complete-to-sparse updates that omit the ID or name.

Related work

• addresses agentclientprotocol/codex-acp#227

AI assisted with implementation, test refinement, verification, and PR text.