Plugin Host (Codex CLI / AI SDK)
  |
  | OpenAI SDK call (generateText/streamText)
  v
index.ts: OpenAIOAuthPlugin
  |
  +-- 1. Load account pool from disk
  |     (AccountManager.loadFromDisk)
  |
  +-- 2. Select best account
  |     (health scoring + session affinity + quota awareness)
  |
  +-- 3. Transform request
  |     (7-step pipeline, see Request Pipeline)
  |
  +-- 4. Execute with failover
  |     (circuit breaker + retry logic + stream failover)
  |
  +-- 5. Update account state
  |     (cooldowns, rate limits, health scores)
  |
  +-- 6. Persist changes
  |     (atomic writes with backup/WAL)
  v
ChatGPT Codex API (https://api.openai.com/v1/realtime/...)

// 1. Generate PKCE challenge + state
const { pkce, state, url } = await createAuthorizationFlow();

// 2. Start local server + open browser
const server = await startLocalOAuthServer({ state });
openBrowserUrl(url);

// 3. Receive callback with authorization code
const { code } = await server.waitForCode(state);

// 4. Exchange code for tokens
const tokens = await exchangeAuthorizationCode(code, pkce.verifier, REDIRECT_URI);
// Result: { access, refresh, expires, idToken }

export const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
export const AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
export const TOKEN_URL = "https://auth.openai.com/oauth/token";
export const REDIRECT_URI = "http://127.0.0.1:1455/auth/callback";
export const SCOPE = "openid profile email offline_access";

~/.codex/multi-auth/
├── settings.json                    # Plugin + dashboard config
├── openai-codex-accounts.json       # Global account pool (V3)
├── openai-codex-accounts.json.bak   # Backup
├── openai-codex-accounts.json.wal   # Write-ahead log
├── quota-cache.json                 # Cached quota snapshots
├── logs/                            # Plugin logs
└── projects/<project-key>/          # Per-project account pools
    └── openai-codex-accounts.json

interface AccountStorageV3 {
  version: 3;
  accounts: Account[];
  activeIndex: number;
  activeIndexByFamily?: Partial<Record<ModelFamily, number>>;
}

interface Account {
  accountId?: string;
  accountIdSource?: "token" | "manual" | "org";
  email?: string;
  refreshToken: string;
  accessToken: string;
  expiresAt: number;
  addedAt: number;
  lastUsed: number;
  healthScore?: number;
  cooldownUntil?: number;
  cooldownReason?: CooldownReason;
  rateLimitResetTimes?: Record<string, number>;
  consecutiveAuthFailures?: number;
}

{
  failureThreshold: 3,        // Open after 3 failures in window
  failureWindowMs: 60_000,    // 60s sliding window
  resetTimeoutMs: 30_000,     // 30s before half-open
  halfOpenMaxAttempts: 1      // 1 test request in half-open
}

const sessionAffinityStore = new SessionAffinityStore({
  ttlMs: 30 * 60 * 1000,  // 30 minutes
  maxEntries: 1000
});

// On request
const preferredIndex = sessionAffinityStore.getPreferredAccountIndex(threadId);

// On successful response
sessionAffinityStore.recordAffinity(threadId, accountIndex);

const liveSync = new LiveAccountSync(
  async () => await reloadAccountManagerFromDisk(),
  { debounceMs: 1000, pollIntervalMs: 2000 }
);
await liveSync.syncToPath(storagePath);

const guardian = new RefreshGuardian(
  () => cachedAccountManager,
  { intervalMs: 60_000, bufferMs: 5 * 60 * 1000 }
);
guardian.start();

const scheduler = new PreemptiveQuotaScheduler();
scheduler.configure({
  enabled: true,
  remainingPercentThresholdPrimary: 10,   // 5h window
  remainingPercentThresholdSecondary: 5,  // 7d window
  maxDeferralMs: 10 * 60 * 1000          // 10 minutes max
});

const deferralMs = scheduler.shouldDeferRequest(accountIndex, modelFamily);
if (deferralMs > 0) {
  await sleep(deferralMs);
}

// Account selection
getPerProjectAccounts()           // Per-project vs global storage
getSessionAffinity()              // Enable session affinity

// Resilience
getNetworkErrorCooldownMs()       // Default 6000ms
getServerErrorCooldownMs()        // Default 4000ms
getRetryAllAccountsMaxRetries()   // Default 3

// Fast session
getFastSession()                  // Low-latency mode
getFastSessionStrategy()          // "hybrid" | "always"
getFastSessionMaxInputItems()     // Default 30

// Token refresh
getTokenRefreshSkewMs()           // Refresh buffer (default 5min)
getProactiveRefreshGuardian()     // Background refresh

// Stream failover
getStreamStallTimeoutMs()         // SSE stall timeout (default 45s)

export const LOG_STAGES = {
  BEFORE_TRANSFORM: "before_transform",
  AFTER_TRANSFORM: "after_transform",
  ERROR_RESPONSE: "error_response",
  SUCCESS_RESPONSE: "success_response",
} as const;

const correlationId = setCorrelationId(
  threadId ? `${threadId}:${Date.now()}` : undefined
);
// All logs for this request tagged with correlationId
clearCorrelationId();

interface RuntimeMetrics {
  totalRequests: number;
  successfulRequests: number;
  failedRequests: number;
  rateLimitedResponses: number;
  serverErrors: number;
  networkErrors: number;
  accountRotations: number;
  streamFailoverAttempts: number;
  streamFailoverRecoveries: number;
  cumulativeLatencyMs: number;
}