@cortexkit/opencode-openai-auth 0.1.1 → 0.1.3

package/README.md

@@ -26,8 +26,35 @@ Restart OpenCode after changing plugin config, then authenticate:
 - Codex request rewriting for OAuth requests, with Codex identity parity.
 - OAuth model filtering and zero-cost display.
 - Prompt-cache stabilizer (`web_search`) that keeps tool-continuation requests on the backend's cached path (on by default).
+- Multiple ChatGPT accounts with automatic reactive fallback on rate limits, configurable routing, and a per-account quota killswitch.
+- Per-turn quota tracking (5-hour + weekly windows) on both transports, with a sidebar readout and an explicit all-accounts refresh.
+- Idle prompt-cache keep-warm, with an optional subagent mode.
+- Leveled, secret-redacting, rotating log file.
+- Interactive in-TUI control surfaces for every command, plus an `openai-auth` CLI for managing fallback accounts headlessly.
 - Optional OpenAI Responses WebSocket transport (HTTP is the default).
 
+## Commands
+
+Each opens an interactive dialog in the TUI and also accepts explicit arguments:
+
+| Command | Arguments | Purpose |
+| --- | --- | --- |
+| `/openai-quota` | — | Show 5h + weekly quota for all accounts. |
+| `/openai-account` | `add [label]` · `switch <id>` · `remove <id>` · `order <a> <b>` | Manage main + fallback accounts (non-destructive switch). |
+| `/openai-routing` | `main-first` · `fallback-first` | Account preference order. |
+| `/openai-killswitch` | `on` · `off` · `set <acct>:<5h>,<1w> ...` | Hard-block accounts below quota thresholds. |
+| `/openai-cachekeep` | `on` · `off` · `subagents on` · `subagents off` | Idle prompt-cache keep-warm. |
+| `/openai-logging` | `<level>` | Set log level live. |
+| `/openai-dump` | `on` · `off` | Toggle transport request dumps. |
+
+CLI (fallback accounts only; the main account comes from `/login openai`):
+
+```text
+openai-auth login [--label <name>] [--headless]
+openai-auth list
+openai-auth remove <id>
+```
+
 ## Configuration
 
 Settings resolve as environment variable → config file (`~/.config/opencode/openai-auth.json`) → default.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { openUrl as openBrowserForLogin } from './util/open-url';

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import{D as $,H as Q,I as W,y as Y,z as Z}from"./index-mrh6k1zf.js";import"./index-0s5tftne.js";import{ea as X}from"./index-hrg6bdgb.js";import{execFileSync as q}from"node:child_process";function T(D,J=process.platform,H=q){try{if(J==="win32"){H("cmd",["/c","start","",D],{stdio:"ignore",timeout:3000});return}H(J==="darwin"?"open":"xdg-open",[D],{stdio:"ignore",timeout:3000})}catch{}}function V(){console.log(`Usage:
+  openai-auth login [--label <name>] [--headless]
+  openai-auth list
+  openai-auth remove <id>
+
+Fallback accounts are stored in:
+  ${$()}`)}function B(D){let J=[],H={};for(let M=0;M<D.length;M++){let z=D[M];if(!z)continue;if(z.startsWith("--")){let C=z.slice(2),G=D[M+1];if(G&&!G.startsWith("--"))H[C]=G,M++;else H[C]=!0}else J.push(z)}return{positional:J,flags:H}}async function E(){let{positional:D,flags:J}=B(process.argv.slice(2)),[H,...M]=D;if(!H||H==="help")V(),process.exit(0);switch(H){case"login":{let z=typeof J.label==="string"?J.label:void 0,C=Boolean(J.headless),{url:G,instructions:K,completion:j}=await Z({label:z,headless:C});if(console.log(`
+Open this URL in your browser and complete sign-in:
+`),console.log(`${G}
+`),K)console.log(`${K}
+`);T(G);let N=await j,O=await Q()??{version:1,accounts:[]};if(N.accountId&&O.mainAccountId&&N.accountId===O.mainAccountId)console.error(`
+Error: that account is already your main (same ChatGPT account).`),console.error("A self-fallback would retry on the account that just returned 429."),process.exit(1);if(Y(O.accounts,N),await W(O),console.log(`
+✓ Added account ${N.id}`),N.label)console.log(`  Label: ${N.label}`);break}case"list":{let z=await Q();if(!z||z.accounts.length===0)console.log("No fallback accounts configured.");else for(let C of z.accounts){let G=C.label,K=[`  ${C.id}`];if(G)K.push(`(${G})`);K.push(C.enabled!==!1?"[enabled]":"[disabled]"),console.log(K.join(" "))}break}case"remove":{let z=M[0];if(!z)console.error("Error: remove requires an account ID."),V(),process.exit(1);let C=await Q();if(!C)console.error("No account store found."),process.exit(1);let G=C.accounts.findIndex((K)=>K.id===z);if(G===-1)console.error(`No account with id "${z}".`),process.exit(1);C.accounts.splice(G,1),await W(C),console.log(`Removed account ${z}.`);break}default:console.error(`Unknown command: ${H}`),V(),process.exit(1)}}if(X.main==X.module)E().catch((D)=>{console.error(D instanceof Error?D.message:String(D)),process.exit(1)});export{T as openBrowserForLogin};

package/dist/commands.d.ts

@@ -0,0 +1,49 @@
+import { type loadAccounts as defaultLoadAccounts } from './core/accounts';
+import type { CacheKeepManager } from './core/cachekeep';
+import type { QuotaManager } from './core/quota-manager';
+import type { RefreshAllQuotaResult } from './core/refresh-all-quota';
+import type { ApplyRequest, ApplyResult, CommandModalName, OpenDialogPayload } from './rpc/protocol';
+export declare const OPENAI_QUOTA_COMMAND_NAME = "openai-quota";
+export declare const OPENAI_ACCOUNT_COMMAND_NAME = "openai-account";
+export declare const OPENAI_ROUTING_COMMAND_NAME = "openai-routing";
+export declare const OPENAI_KILLSWITCH_COMMAND_NAME = "openai-killswitch";
+export declare const OPENAI_DUMP_COMMAND_NAME = "openai-dump";
+export declare const OPENAI_LOGGING_COMMAND_NAME = "openai-logging";
+export declare const OPENAI_CACHEKEEP_COMMAND_NAME = "openai-cachekeep";
+export declare const MODAL_COMMANDS: CommandModalName[];
+export interface CommandContext {
+    accountStoragePath: string;
+    quotaManager: QuotaManager;
+    loadAccounts: typeof defaultLoadAccounts;
+    client: {
+        auth: {
+            set: (input: {
+                path: {
+                    id: string;
+                };
+                body: {
+                    type: string;
+                    access?: string;
+                    refresh: string;
+                    expires?: number;
+                };
+            }) => Promise<unknown>;
+        };
+    };
+    /** Session ID for pushNotification delivery. */
+    sessionId?: string;
+    /** If set, pushNotification is wired up and can deliver feedback to the user. */
+    notify?: (payload: OpenDialogPayload) => void;
+    /** Refresh the sidebar-state file so the TUI modal shows current data. */
+    refreshSidebar?: () => Promise<void>;
+    /** Actively poll wham/usage for all accounts (main + fallbacks). */
+    refreshAllQuota?: () => Promise<RefreshAllQuotaResult[]>;
+    /** Prompt-cache cachekeep manager. Set when the command is wired. */
+    cacheKeepManager?: CacheKeepManager | null;
+    /** Updates the live loader's persisted-enabled cachekeep gate. */
+    setCacheKeepEnabled?: (enabled: boolean) => void;
+    /** Updates the live loader's persisted-subagent cachekeep gate. */
+    setCacheKeepSubagents?: (enabled: boolean) => void;
+}
+export declare function buildDialogPayload(command: CommandModalName, args: string, ctx: CommandContext): Promise<OpenDialogPayload>;
+export declare function applyCommand(request: ApplyRequest, ctx: CommandContext): Promise<ApplyResult>;

package/dist/core/accounts.d.ts

@@ -0,0 +1,227 @@
+import type { ProviderQuotaFn, ProviderRefreshFn, QuotaWindowName } from './provider.ts';
+import { PRIMARY, SECONDARY } from './provider.ts';
+export declare const ACCOUNT_FILE_NAME = "openai-auth.json";
+export declare const ACCOUNT_STATE_FILE_NAME = "openai-auth-state.json";
+export declare function getAccountStoragePath(): string;
+export declare function getAccountStatePath(configPath?: string): string;
+export type { QuotaWindowName };
+export { PRIMARY, SECONDARY };
+export type AccountQuotaWindow = {
+    usedPercent: number;
+    remainingPercent: number;
+    resetsAt?: string;
+    checkedAt: number;
+};
+export type OAuthQuotaSnapshot = Partial<Record<QuotaWindowName, AccountQuotaWindow>>;
+export type AccountBase = {
+    id: string;
+    label?: string;
+    enabled?: boolean;
+    addedAt?: number;
+    lastUsed?: number;
+    /** Stable ChatGPT account identifier extracted from the OAuth token claims. */
+    accountId?: string;
+};
+export type AccountOperationError = {
+    message: string;
+    checkedAt: number;
+    nextRetryAt?: number;
+    retryCount?: number;
+    tokenHash?: string;
+};
+export type OAuthAccount = AccountBase & {
+    type: 'oauth';
+    access?: string;
+    refresh: string;
+    expires?: number;
+    lastRefreshedAt?: number;
+    lastRefreshError?: AccountOperationError;
+    lastQuotaRefreshError?: AccountOperationError;
+    quota?: Partial<Record<QuotaWindowName, AccountQuotaWindow>>;
+};
+export type ApiKeyAccount = AccountBase & {
+    type: 'api';
+    apiKey?: string;
+    baseURL: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+};
+export type FallbackAccount = OAuthAccount | ApiKeyAccount;
+export declare function isOAuthAccount(account: FallbackAccount): account is OAuthAccount;
+export declare function isApiKeyAccount(account: FallbackAccount): account is ApiKeyAccount;
+export declare function isValidApiBaseURL(value: string | undefined): boolean;
+export type RoutingMode = 'main-first' | 'fallback-first';
+export type KillswitchThresholds = Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
+export type KillswitchConfig = {
+    enabled?: boolean;
+    main?: KillswitchThresholds;
+    accounts?: Record<string, KillswitchThresholds>;
+};
+export type AccountStorage = {
+    version: 1;
+    main?: {
+        type: 'opencode';
+        provider: 'openai';
+    };
+    routing?: {
+        mode?: RoutingMode;
+        activeId?: string;
+    };
+    fallbackOn?: number[];
+    refresh?: {
+        enabled?: boolean;
+        intervalMinutes?: number;
+        refreshBeforeExpiryMinutes?: number;
+        mainLastRefreshError?: AccountOperationError;
+        mainRefreshLeaseId?: string;
+        mainRefreshLeaseUntil?: number;
+        mainRefreshLeaseTokenHash?: string;
+    };
+    quota?: {
+        enabled?: boolean;
+        checkIntervalMinutes?: number;
+        refreshEveryNRequests?: number;
+        minimumRemaining?: Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
+        failClosedOnUnknownQuota?: boolean;
+        showToasts?: boolean;
+        mainQuota?: OAuthQuotaSnapshot;
+        mainQuotaCheckedAt?: number;
+        mainQuotaToken?: string;
+        mainLastQuotaApiError?: AccountOperationError;
+    };
+    dump?: {
+        enabled?: boolean;
+    };
+    costZeroing?: {
+        enabled?: boolean;
+    };
+    killswitch?: KillswitchConfig;
+    logging?: {
+        level?: string;
+    };
+    cachekeep?: {
+        enabled?: boolean;
+        subagents?: boolean;
+    };
+    /** Stable ChatGPT account identifier of the main account (extracted from OAuth token). */
+    mainAccountId?: string;
+    accounts: FallbackAccount[];
+};
+export declare function isCostZeroingEnabled(storage: Pick<AccountStorage, 'costZeroing'>): boolean;
+export type AccountRuntimeEntry = Partial<Pick<OAuthAccount, 'access' | 'refresh' | 'expires' | 'lastUsed' | 'lastRefreshedAt' | 'lastRefreshError' | 'lastQuotaRefreshError' | 'quota'> & Pick<ApiKeyAccount, 'apiKey' | 'lastUsed'>>;
+export type AccountRuntimeState = {
+    version: 1;
+    main?: {
+        quota?: OAuthQuotaSnapshot;
+        quotaCheckedAt?: number;
+        quotaToken?: string;
+        lastQuotaApiError?: AccountOperationError;
+        lastRefreshError?: AccountOperationError;
+        refreshLeaseId?: string;
+        refreshLeaseUntil?: number;
+        refreshLeaseTokenHash?: string;
+    };
+    accounts?: Record<string, AccountRuntimeEntry>;
+};
+export type AccountStateSaveScope = {
+    mainQuota?: boolean;
+    mainRefresh?: boolean;
+    accounts?: true | string[];
+};
+export type AccountManagerOptions = {
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+    configPath?: string;
+    onFallbackStorageChanged?: () => void;
+    /** Provider token-refresh function (constructor-injected). */
+    refreshFn?: ProviderRefreshFn;
+    /** Provider quota-fetch function (constructor-injected, OPTIONAL wham/usage supplement). */
+    fetchQuotaFn?: ProviderQuotaFn;
+    /** QuotaManager instance for unified cache (constructor-injected). */
+    quotaManager?: import('./quota-manager.ts').QuotaManager;
+};
+export type AccountRefreshError = {
+    accountId: string;
+    message: string;
+};
+export declare const DEFAULT_KILLSWITCH_THRESHOLDS: {
+    primary: number;
+    secondary: number;
+};
+export declare function loadAccounts(path?: string): Promise<AccountStorage | null>;
+export declare function saveAccounts(storage: AccountStorage, path?: string): Promise<void>;
+export declare function saveAccountState(storage: AccountStorage, path?: string, scope?: AccountStateSaveScope): Promise<void>;
+export declare function shouldFallbackStatus(status: number, storage: AccountStorage | null): boolean;
+export declare function quotaSnapshotPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null): boolean;
+export declare function isKillswitchEnabled(storage: AccountStorage | null): boolean;
+export declare function killswitchPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, accountId?: string): boolean;
+export declare function killswitchRetryAfterSeconds(mainQuota: OAuthQuotaSnapshot | undefined, fallbackAccounts: Array<{
+    quota?: OAuthQuotaSnapshot;
+}>, now: number): number;
+/**
+ * Migrate an existing single-slot token into the multi-account store.
+ *
+ * Reads the existing token via the caller-provided `getAuth` (the ONLY
+ * read path — there is no `client.auth.get`).  If a token exists and the
+ * config file is NOT yet an account store (content discriminator), seeds
+ * it as the primary OAuth account.
+ *
+ * Idempotent: a second run is a no-op because the content discriminator
+ * will already match.
+ *
+ * Tolerates expired/revoked tokens (migrates them; refresh handles validity).
+ *
+ * Guards against first-run races with `acquireRefreshFileLock`.
+ */
+export declare function migrateIfNeeded(existingToken: {
+    type: 'oauth';
+    access: string;
+    refresh: string;
+    expires: number;
+} | undefined, path?: string): Promise<void>;
+export declare function getQuotaCheckIntervalMs(storage: AccountStorage | null): number;
+export declare function getRefreshIntervalMs(storage: AccountStorage | null): number;
+export declare class FallbackAccountManager {
+    private readonly now;
+    private readonly fetchImpl;
+    private readonly configPath;
+    private readonly refreshPromises;
+    private refreshTimer;
+    private quotaTimer;
+    readonly quotaManager: import('./quota-manager.ts').QuotaManager | null;
+    private readonly onFallbackStorageChanged;
+    private readonly options;
+    constructor(options?: AccountManagerOptions);
+    /**
+     * Seed QuotaManager from persisted account.quota if no cache entry exists
+     * yet. Prevents unnecessary API calls when the on-disk snapshot is fresh.
+     */
+    private seedFallbackQuota;
+    load(): Promise<AccountStorage | null>;
+    save(storage: AccountStorage, accountIds?: string[]): Promise<void>;
+    startBackgroundRefresh(): void;
+    stopBackgroundRefresh(): void;
+    getUsableFallbackAccounts(existingStorage?: AccountStorage | null): Promise<OAuthAccount[]>;
+    markUsed(account: FallbackAccount): Promise<void>;
+    accountPassesQuotaPolicy(account: OAuthAccount, storage: AccountStorage | null): boolean;
+    /**
+     * Return the account with its quota overlaid from the unified QuotaManager
+     * cache (token-bound) when available, so quota-policy decisions use the same
+     * source of truth as the staleness check. Falls back to the stored
+     * account.quota when no manager is wired or the cache has no entry.
+     */
+    private quotaPolicyAccount;
+    refreshDueAccounts(): Promise<void>;
+    refreshQuotaForDueAccounts(): Promise<void>;
+    refreshQuotaForAllAccounts(options?: {
+        force?: boolean;
+    }): Promise<{
+        storage: AccountStorage | null;
+        errors: AccountRefreshError[];
+    }>;
+    refreshAccount(account: OAuthAccount, storage: AccountStorage, options?: {
+        force?: boolean;
+    }): Promise<OAuthAccount>;
+    private waitForConcurrentFallbackRefresh;
+    private refreshAccountNow;
+    refreshAccountQuota(account: OAuthAccount, storage: AccountStorage): Promise<void>;
+}

package/dist/core/atomic-write.d.ts

@@ -0,0 +1 @@
+export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;

package/dist/core/backoff.d.ts

@@ -0,0 +1,53 @@
+export declare const NON_TRANSIENT_REFRESH_RETRY_DELAY_MS: number;
+export declare function isTransientRefreshError(error: unknown): boolean;
+export declare function isTransientQuotaError(error: unknown): boolean;
+export declare function hashRefreshToken(refreshToken: string): string;
+export declare function buildRefreshOperationError(input: {
+    error: unknown;
+    now: number;
+    refreshToken: string;
+    previous?: {
+        message: string;
+        checkedAt: number;
+        nextRetryAt?: number;
+        retryCount?: number;
+        tokenHash?: string;
+    };
+}): {
+    message: string;
+    checkedAt: number;
+    nextRetryAt: number;
+    retryCount: number;
+    tokenHash: string;
+};
+export declare function refreshBackoffActive(error: {
+    nextRetryAt?: number;
+    tokenHash?: string;
+} | undefined, refreshToken: string | undefined, now: number): boolean;
+export declare function formatRefreshBackoffMessage(error: {
+    message: string;
+    nextRetryAt?: number;
+}, now: number): string;
+export declare function buildQuotaOperationError(input: {
+    error: unknown;
+    now: number;
+    previous?: {
+        message: string;
+        checkedAt: number;
+        nextRetryAt?: number;
+        retryCount?: number;
+    };
+}): {
+    message: string;
+    checkedAt: number;
+    nextRetryAt: number;
+    retryCount: number;
+};
+export declare function quotaBackoffActive(error: {
+    nextRetryAt?: number;
+} | undefined, now: number): boolean;
+export declare function formatQuotaBackoffMessage(error: {
+    message: string;
+    nextRetryAt?: number;
+}, now: number): string;
+export declare function parseRetryAfter(value: string | undefined | null): number | undefined;

package/dist/core/cachekeep.d.ts

@@ -0,0 +1,95 @@
+export interface Target {
+    bodyText: string;
+    accountId: string | undefined;
+    chatgptAccountId?: string;
+    route: 'main';
+    cacheExpiresAt: number;
+    lastRealRequestAt: number;
+    lastWarmedAt?: number;
+    backoffUntil?: number;
+    replayHeaders: Record<string, string>;
+    isSubagent?: boolean;
+}
+export interface CacheKeepManagerOptions {
+    fetchImpl: typeof fetch;
+    getMainToken: () => Promise<string>;
+    refreshFallback: (accountId: string) => Promise<string>;
+    codexResponsesUrl: string;
+    logger: {
+        info: (msg: string, data?: unknown) => void;
+        warn: (msg: string, data?: unknown) => void;
+        debug: (msg: string, data?: unknown) => void;
+        error: (msg: string, data?: unknown) => void;
+    };
+    now: () => number;
+    ttlMs?: number;
+    leadMs?: number;
+    maxDurationMs?: number;
+    maxIdleWarmMs?: number;
+    maxSubagentIdleMs?: number;
+    tickIntervalMs?: number;
+    maxTargets?: number;
+    maxBytes?: number;
+}
+export interface CacheKeepStatus {
+    running: boolean;
+    tracked: number;
+    generatedAt: number;
+    startedAt: number | null;
+    maxIdleWarmMs: number;
+    maxSubagentIdleMs: number;
+    ttlMs: number;
+    leadMs: number;
+    targets: Array<{
+        sessionKey: string;
+        accountId: string | undefined;
+        route: 'main';
+        cacheExpiresAt: number;
+        lastRealRequestAt: number;
+        lastWarmedAt?: number;
+        backoffUntil?: number;
+        bodyBytes: number;
+    }>;
+}
+export interface KeepwarmCapture {
+    sessionKey: string;
+    bodyText: string;
+    replayHeaders: Record<string, string>;
+    isSubagent: boolean;
+}
+export declare function buildKeepwarmCapture(input: {
+    enabled: boolean;
+    includeSubagents: boolean;
+    headers: Headers;
+    body: unknown;
+}): KeepwarmCapture | undefined;
+export declare function buildKeepwarmBody(bodyText: string): string;
+export declare class CacheKeepManager {
+    private readonly targets;
+    private readonly fetchImpl;
+    private readonly getMainToken;
+    private readonly refreshFallback;
+    private readonly codexResponsesUrl;
+    private readonly log;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly leadMs;
+    private readonly maxIdleWarmMs;
+    private readonly maxSubagentIdleMs;
+    private readonly tickIntervalMs;
+    private readonly maxTargets;
+    private readonly maxBytes;
+    private timer;
+    private startedAt;
+    private totalBytes;
+    private tickInFlight;
+    private logPayload;
+    constructor(options: CacheKeepManagerOptions);
+    track(sessionKey: string, bodyText: string, accountId: string | undefined, chatgptAccountId?: string, replayHeaders?: Record<string, string>, isSubagent?: boolean): void;
+    private pruneStale;
+    start(): void;
+    stop(): void;
+    status(): CacheKeepStatus;
+    tick(): Promise<void>;
+    private prewarm;
+}

package/dist/core/oauth.d.ts

@@ -0,0 +1,126 @@
+export declare const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const ISSUER = "https://auth.openai.com";
+export declare const OAUTH_PORT = 1455;
+export declare const OAUTH_POLLING_SAFETY_MARGIN_MS = 3000;
+export declare const USER_AGENT = "cortexkit-opencode-openai-auth/0.1.3";
+export interface PkceCodes {
+    verifier: string;
+    challenge: string;
+}
+export declare function base64UrlEncode(buffer: ArrayBuffer): string;
+export declare function generatePKCE(): Promise<PkceCodes>;
+export interface IdTokenClaims {
+    chatgpt_account_id?: string;
+    email?: string;
+    organizations?: Array<{
+        id: string;
+    }>;
+    'https://api.openai.com/auth'?: {
+        chatgpt_account_id?: string;
+    };
+}
+export declare function parseJwtClaims(token: string): IdTokenClaims | undefined;
+export declare function extractAccountIdFromClaims(claims: IdTokenClaims): string | undefined;
+export interface TokenResponse {
+    id_token: string;
+    access_token: string;
+    refresh_token: string;
+    expires_in?: number;
+}
+export declare function extractAccountId(tokens: TokenResponse): string | undefined;
+export declare function buildAuthorizeUrl(redirectUri: string, pkce: PkceCodes, state: string): string;
+export declare function exchangeCodeForTokens(code: string, redirectUri: string, pkce: PkceCodes): Promise<TokenResponse>;
+export declare function escapeHtml(value: string): string;
+export declare const HTML_SUCCESS = "<!doctype html>\n<html>\n  <head>\n    <title>CortexKit OpenAI Auth - Authorization Successful</title>\n    <style>\n      body {\n        font-family:\n          system-ui,\n          -apple-system,\n          sans-serif;\n        display: flex;\n        justify-content: center;\n        align-items: center;\n        height: 100vh;\n        margin: 0;\n        background: #131010;\n        color: #f1ecec;\n      }\n      .container {\n        text-align: center;\n        padding: 2rem;\n      }\n      h1 {\n        color: #f1ecec;\n        margin-bottom: 1rem;\n      }\n      p {\n        color: #b7b1b1;\n      }\n    </style>\n  </head>\n  <body>\n    <div class=\"container\">\n      <h1>Authorization Successful</h1>\n      <p>You can close this window and return to OpenCode.</p>\n    </div>\n    <script>\n      setTimeout(() => window.close(), 2000)\n    </script>\n  </body>\n</html>";
+export declare const HTML_ERROR: (error: string) => string;
+export interface PendingOAuth {
+    pkce: PkceCodes;
+    state: string;
+    resolve: (tokens: TokenResponse) => void;
+    reject: (error: Error) => void;
+}
+export declare function flowCleanup(state: string): void;
+export declare function startOAuthServer(): Promise<{
+    port: number;
+    redirectUri: string;
+}>;
+export declare function stopOAuthServer(): void;
+export declare function resetOAuthStateForTest(): void;
+export declare function waitForOAuthCallback(pkce: PkceCodes, state: string, timeoutMs?: number): Promise<TokenResponse>;
+export interface DeviceAuthInit {
+    device_auth_id: string;
+    user_code: string;
+    interval: string;
+}
+export declare function beginDeviceAuth(): Promise<{
+    deviceData: DeviceAuthInit;
+    url: string;
+    instructions: string;
+}>;
+export declare function completeDeviceAuth(deviceData: DeviceAuthInit, signal?: AbortSignal): Promise<TokenResponse>;
+/**
+ * Minimal shape of a fallback OAuth account for ingestion. Matches the
+ * fields used by upsertAccount and beginAccountLogin, compatible with
+ * the full OAuthAccount type in accounts.ts.
+ */
+export interface IngestAccount {
+    id: string;
+    label?: string;
+    type: 'oauth';
+    access?: string;
+    refresh: string;
+    expires?: number;
+    enabled: boolean;
+    addedAt: number;
+    lastUsed: number;
+    /** Stable ChatGPT account identifier from the OAuth token claims. */
+    accountId?: string;
+}
+export interface AccountStorageLike {
+    version: 1;
+    mainAccountId?: string;
+    accounts: IngestAccount[];
+}
+/**
+ * Dedup by stable accountId first (strongest signal — same ChatGPT account
+ * added twice with different labels must merge), then by id, then by label.
+ * If found, merge-update preserving addedAt. Otherwise push.
+ * Re-running `add --label work` is idempotent.
+ *
+ * Accepts the accounts array directly (not the whole storage object) to
+ * avoid coupling to any particular storage shape.
+ */
+export declare function upsertAccount<T extends {
+    id: string;
+    label?: string;
+    accountId?: string;
+    addedAt?: number;
+}>(accounts: T[], account: T): number;
+export interface BeginAccountLoginOptions {
+    label?: string;
+    headless?: boolean;
+    signal?: AbortSignal;
+}
+export interface BeginAccountLoginResult {
+    url: string;
+    instructions: string;
+    /** Resolves after the user completes the OAuth flow with a ready-to-ingest account. */
+    completion: Promise<IngestAccount>;
+}
+/**
+ * Split-return OAuth flow entry point.
+ *
+ * Browser flow (default):
+ *   1. Start OAuth server, generate PKCE, build authorize URL
+ *   2. Return { url, instructions, completion } — url is ready immediately
+ *   3. completion resolves after browser callback + token exchange
+ *
+ * Headless flow:
+ *   1. Begin device auth
+ *   2. Return { url, instructions, completion }
+ *   3. completion polls device endpoint + exchanges for tokens
+ *
+ * The split return allows the TUI command to show the URL before the
+ * (potentially 30-60s) wait, avoiding a deadlock.
+ */
+export declare function beginAccountLogin(opts?: BeginAccountLoginOptions): Promise<BeginAccountLoginResult>;

package/dist/core/provider.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Provider injection seam — shared types and the 2 Codex provider fns.
+ *
+ * Both fns are constructor-injected into FallbackAccountManager and
+ * QuotaManager so the generic core never imports provider specifics
+ * directly.
+ */
+import type { OAuthQuotaSnapshot } from './accounts.ts';
+export type QuotaWindowName = string;
+export declare const PRIMARY: QuotaWindowName;
+export declare const SECONDARY: QuotaWindowName;
+export interface ProviderHttpError extends Error {
+    status?: number;
+    retryAfter?: number;
+    /** True when this error originated from a token-refresh call (not a quota fetch). */
+    isRefreshError?: boolean;
+}
+export type ProviderRefreshFn = (input: {
+    refreshToken: string;
+    fetchImpl: typeof fetch;
+    now: () => number;
+}) => Promise<{
+    access: string;
+    refresh: string;
+    expires: number;
+    expiresIn: number;
+}>;
+export type ProviderQuotaFn = (input: {
+    accessToken: string;
+    fetchImpl: typeof fetch;
+    now: () => number;
+}) => Promise<OAuthQuotaSnapshot>;
+export declare const CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const CODEX_ISSUER = "https://auth.openai.com";
+/**
+ * Core Codex OAuth refresh — the single entry point for refreshing an
+ * OpenAI OAuth token.  Used by both the legacy refreshAccessToken in
+ * index.ts AND the FallbackAccountManager (via constructor injection).
+ *
+ * Throws a ProviderHttpError carrying `.status` (from the HTTP response)
+ * and `.retryAfter` (parsed from Retry-After) so backoff machinery can
+ * duck-type them without instanceof checks.
+ */
+export declare function codexRefreshFn(input: {
+    refreshToken: string;
+    fetchImpl: typeof fetch;
+    now: () => number;
+}): Promise<{
+    access: string;
+    refresh: string;
+    expires: number;
+    expiresIn: number;
+}>;
+export declare function whamUsageFn(input: {
+    accessToken: string;
+    fetchImpl: typeof fetch;
+    now: () => number;
+    accountId?: string;
+}): Promise<OAuthQuotaSnapshot>;