feat(usage): show ZCode Coding Plan quota

[guanbear]

Summary

Adds a ZCode Coding Plan usage meter to Orca's existing provider usage UI.

This is intentionally independent from ZCode launch and orchestration behavior: it reads the user's local ZCode credential, fetches quota from an allowlisted official endpoint, and publishes normalized rate-limit state.

Dependency

• Draft follow-up to feat(agents): add ZCode as a first-class supported agent #13965 for the first-class zcode provider identity.
• Restacked onto the new core-only feat(agents): add ZCode as a first-class supported agent #13965 branch; it no longer contains Desktop fallback, orchestration, or transcript changes.
• Keep as Draft until feat(agents): add ZCode as a first-class supported agent #13965 lands.

What Changed

• Adds a bounded ZCode Coding Plan quota fetcher with a 15-second timeout.
• Wires ZCode into provider state, polling, stale handling, refresh, status-bar visibility, tooltip copy, and settings search.
• Preserves existing provider visibility and status-bar customization behavior.

Current Coding Plan Promotion

ZCode currently advertises a promotional 0.67 usage coefficient for eligible Coding Plan calls, equivalent to roughly 1.5× effective quota. This PR does not apply that coefficient itself; it displays the usage percentages reported by the provider, avoiding double adjustment. Eligibility and duration remain provider-controlled.

Visual Proof

Validation

• 12 affected Vitest suites pass (157 tests).
• Node, web, and CLI typechecks pass on Node 24.
• Formatting, lint, and git diff --check pass.

Security

• Reads credential material in the main process only.
• Restricts quota requests to the configured official ZCode hosts.
• Does not log, persist, or expose credentials in renderer state.
• Treats missing credentials and malformed responses as explicit provider errors.

AI Disclosure

Implemented with OpenAI Codex and validated against current Orca main.

[guanbear]

Restacked the single ZCode usage-meter commit onto the refreshed first-class ZCode head (15a4791c8), so this draft no longer carries the old conflicting stack.

Fresh validation:

• 8 affected Vitest files: 352 passed
• Node TypeScript check passed
• full pnpm run lint passed, including localization and max-lines ratchet
• git diff --check passed

Keeping this Draft until #13965 lands, since it intentionally depends on the first-class ZCode provider identity.

[guanbear]

Restacked the single ZCode usage-meter commit onto the refreshed #13965 head and migrated its tests to the current split service/UI test layout. Validation: 151 affected tests passed; Node and Web typechecks passed; changed-file oxlint and diff check passed. Keeping this Draft until #13965 lands. Fork workflow runs are awaiting maintainer approval.

[guanbear]

Restacked onto the refreshed #13965 head and current main (6faaf3af). The zcode: null web rate-limits stub moved into preload-api/web-rate-limits-api.ts following the #16181 preload split. Validation: Node/Web typecheck passes; fetcher, rate-limits service, store slice, and provider-visibility/gating suites pass (38 tests).

[nwparker]

Leaving this open — usage tracking did not ship with #22464, so the need is still live. #21757 and #18506 are both still open too.

One development worth your time before you rebase anything: Z.ai open-sourcing the CLI changed the options here. ZCode records usage locally, in ~/.zcode/cli/db/db.sqlite, in a model_usage table written per model request:

started_at, provider_id, model_id, variant, agent, mode,
input_tokens, output_tokens, reasoning_tokens,
cache_creation_input_tokens, cache_read_input_tokens,
computed_total_tokens, provider_total_tokens, status, duration_ms

with create index model_usage_started_model_idx on model_usage(started_at, provider_id, model_id). There are turn_usage and tool_usage tables alongside it. I confirmed 93 real rows on a machine with ZCode installed.

That matters because the main hesitation on #21757 was exactly the thing this PR does — calling an endpoint that isn't documented for third-party callers. A local provider (same shape as the Muse Code one in #22379) sidesteps it: no API key, no credential read, works offline.

The honest tradeoff: local records give you consumption, not remaining quota. If the status-bar meter is the point, that still needs an endpoint, and @ArtemBozhenko's detail on #18506 — key in Authorization with no Bearer prefix — is the useful part to keep. Possibly both: local for the breakdown, endpoint for the quota.

This branch is stacked on #13965, which I've closed as superseded, so it won't rebase cleanly as-is. A fresh PR against main would be easier for both of us. Your fetcher's host allowlisting and its unavailable/error states were the careful parts and worth carrying over either way.

[guanbear]

Thanks for the detailed guidance. I replaced this stacked draft with #23520, based directly on current main.

The new draft keeps the quota meter because local model_usage can show consumption but cannot determine remaining allowance. It adds CREDIT_LIMIT support and separates the MCP TIME_LIMIT, using CodexBar/Pulse response semantics while following ZCode's own raw Authorization header for the configured API key. The host allowlist, explicit unavailable/error states, and synthetic tests are retained. The PR calls out the undocumented endpoint and OAuth-only limitation for review.

Closing this superseded branch so discussion can continue on #23520.