pi-xai-oauth AGENTS.md

AGENTS.md — AI Agent Operations Manual for pi-xai-oauth

For AI coding agents only. Keep this file machine-readable and concise. Human-facing docs live in README.md.

Project Overview

pi-xai-oauth is a pi-package that registers the optional xAI OAuth provider (xai-auth) and the authenticated account's OAuth-visible Grok model catalog, with Grok 4.6 as the curated offline fallback. Opt-in network tools and /xai-usage also work with Pi's built-in xai SuperGrok/X Premium chat provider; setup seeds defaultProvider: xai only when unset and never overwrites an existing provider choice.

Core flow: bin/setup.js → pi install → bounded catalog selection in extensions/xai/catalog.ts → provider registration in extensions/xai-oauth.ts → browser PKCE or bounded device authorization in extensions/xai/oauth.ts / extensions/xai/device-auth.ts → pinned browser OIDC/JWKS validation in extensions/xai/oidc.ts → streaming via xAI API helpers in extensions/xai/responses.ts; explicit revision-pinned subscription usage lives in extensions/xai/usage.ts.

Key Commands (Exact, Copy-Paste Ready)

• Install / setup: node bin/setup.js or npm run setup
• Install as pi extension: pi install npm:pi-xai-oauth
• Full policy/unit/loader gate: npm test
• Focused Vitest suite: npm run test:unit -- tests/oauth/browser-login.test.ts
• V8 coverage: npm run test:coverage
• Real Pi loader smoke: npm run test:loader
• Run TypeScript: npm run typecheck (production, tests, fixtures, config)
• Verify Pi policy/package metadata: npm run compatibility:check
• Verify exact packed Pi boundaries: npm run compatibility:boundaries
• Verify the scoped GitHub Packages mirror: node scripts/verify-github-package.js
• Evaluate an unadvertised Pi candidate: node scripts/run-compatibility-matrix.js X.Y.Z --candidate
• Git: Always work on feature branches and confirm the active branch before edits.

Architecture & Boundaries (MUST / MUST NOT)

MUST:

• Register providers via pi.registerProvider("xai-auth", { ... })
• Keep browser PKCE S256 with local callback server as the first/default login method
• Offer device authorization through pi's native selector/device-code callbacks for remote/headless human login
• Pin the device and token endpoints; wait before polling; honor interval plus cumulative slow-down; bound expiry; propagate cancellation
• Require matching state for every HTTP or pasted browser authorization callback before token exchange
• Validate retained fresh-login ID tokens against pinned first-party discovery/JWKS, ES256, issuer, audience, expiry, and nonce
• Support reasoning levels: none / low / medium / high
• Reuse ~/.grok/auth.json when possible without deleting or revoking it
• Fetch OAuth-visible models only from the pinned authenticated CLI proxy /models-v2 endpoint
• Treat successful catalog responses as exact entitlement state; additions appear and removals disappear
• Keep the normalized token-free catalog cache atomic and apply the documented TTL/stale/fallback policy
• Preserve known model metadata and compatibility behavior without inventing unentitled model families; known aliases and independently verified OAuth request slugs may be advertised only while their entitlement source is present at registration/runtime (cache stays exact)
• Keep both Pi peers aligned to the checked-in bounded range in compatibility/pi-versions.json
• Keep npmjs pi-xai-oauth canonical and publish GitHub Packages only as the exact scoped mirror @blockedpath/pi-xai-oauth; setup must treat both names as aliases and prevent duplicate registration
• Install/report exact Pi matrix versions from a clean packed package; never reuse the repository lockfile for boundary jobs
• Keep tests/, its fixtures, vitest.config.mts, and tsconfig.json inside the packed tarball; scripts/run-compatibility-matrix.js extracts the pack and runs npm test plus npm run typecheck inside it, so excluding them silently breaks both exact-Pi boundary jobs
• Keep normal Pi dev dependencies exact at the policy's latest tested release and review candidate releases before widening support
• Resolve x-userid transiently from the pinned authenticated CLI-proxy /user endpoint before any billing request
• Keep /xai-usage explicit, and keep its optional status off by default, session-scoped, bounded, and inactive outside xAI models