provider-onboarding

Provider Onboarding & Credential Architecture

This document defines the requirements, shared machinery, and safety invariants for onboarding new quota providers or modifying existing adapters in quota-axi.

Clean-Room & Dependency Policy

• Clean-room implementation: Adapter behavior (retry-after handling, snake/camel field tolerance, window parsing) must be an original implementation derived solely from the vendor's own HTTP/OAuth 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.
• HTTP & proxy handling: Remote HTTP requests must route through src/lib/http.ts (providerFetch) so standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY policies apply consistently without leaking proxy credentials in logs. Do not use global fetch directly.
  • Node 26 compatibility: src/lib/http.ts pairs the installed undici build's ProxyAgent with that same build's fetch because Node's built-in global fetch only accepts dispatchers from its bundled undici, and Node 26 rejects external ProxyAgent instances with InvalidArgumentError: invalid onError method.
• Process table reads: Any process-table inspection (e.g. Antigravity loopback detection or Claude process checks) must route through currentUserProcessListArgs in src/lib/process.ts to handle platform flag differences portably (Linux procps rejects BSD -x alongside -u).

Provider Onboarding Checklist

When adding a new provider or migrating an existing adapter:

1. Enumerate every source in ownership-stability order:
   • Declare source priority via a named constant (e.g. COPILOT_SOURCE_ORDER).
   • Distinguish absent, structurally_invalid, unsupported, read_error, and resolved (stored-valid or stored-expired) at the typed local resolution boundary.
   • Route Pi agent entries through classifyPiAuthEntry in src/lib/pi-auth-store.ts.
   • Derive credentialPresent once from local resolution rather than ad hoc at call sites.