opencode-auth-load-balancer 0.2.1

package/dist/notify.d.ts

@@ -0,0 +1,47 @@
+import type { PoolAccount } from './types';
+/** The slice of the opencode SDK client we need to show a toast. */
+export interface ToastClient {
+    tui: {
+        showToast(opts: {
+            body: {
+                title?: string;
+                message: string;
+                variant: 'info' | 'success' | 'warning' | 'error';
+                duration?: number;
+            };
+        }): Promise<unknown>;
+    };
+}
+/**
+ * Toast (once) when a provider's in-use account changes — the user's "which account
+ * is in use" indicator. De-duped per provider so a sticky session doesn't re-toast.
+ * Best-effort: a failed toast never affects the request.
+ */
+export declare function notifyOnSwitch(client: ToastClient, providerID: string, account: PoolAccount): Promise<void>;
+/**
+ * Toast (once per account + source-model + exhaustion window) when a request's
+ * model was auto-downgraded to a fallback because its MODEL TIER's weekly cap
+ * is exhausted — so the downgrade is visible, not silent. The de-dupe value is
+ * scoped to the latest tier exhaustion window (the max entry of
+ * `modelCooldownsUntil`): turns within one window toast once, but after the
+ * tier cap RESETS and later re-exhausts (a NEW window, hence a new cooldown
+ * timestamp) the downgrade toasts again — otherwise every window after the
+ * first in a process's lifetime would be silent. A source-model change
+ * re-toasts within a window too. The scan ignores tier entries that have
+ * already expired (`until <= now`): nothing in the codebase purges a stale
+ * `modelCooldownsUntil[tier]` entry once its window passes, so an old,
+ * long-reset tier's timestamp can otherwise outrank a fresh, currently-active
+ * tier's smaller timestamp and mask a genuinely NEW exhaustion window behind
+ * an unchanged de-dupe key — silently suppressing the toast this function
+ * exists to guarantee. When the caller supplies `fromTier` (the SPECIFIC
+ * tier that triggered this downgrade — `ModelFallback.fromTier`, threaded
+ * through from `downgradeModel`), that tier's own window is used directly
+ * instead of the max-scan: with two tiers simultaneously active on one
+ * account (e.g. `fable` capped, downgrade to `opus`, `opus` ALSO capped,
+ * downgrade to `sonnet`) the max-scan could pick whichever window is later,
+ * not necessarily the one that actually triggered this toast. Callers that
+ * don't supply `fromTier` (older call sites, or a provider with no tier
+ * concept) keep the max-scan heuristic unchanged. Best-effort: a failed
+ * toast never affects the request.
+ */
+export declare function notifyModelFallback(client: ToastClient, providerID: string, account: PoolAccount, fromModel: string, toModel: string, fromTier?: string): Promise<void>;

package/dist/pool/lock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cross-process advisory file lock.
+ *
+ * The in-process promise-chain mutex in `store.ts` only serializes mutations
+ * within ONE opencode process. Two opencode instances (two TUI windows, a server
+ * + a TUI, two project dirs) share the single pool file and can therefore race a
+ * read-modify-write — or, worse, both spend the same single-use OAuth refresh
+ * token and brick an account. This lock serializes those critical sections across
+ * processes using an atomic `mkdir` (which fails if the directory already exists
+ * on every OS) as the mutual-exclusion primitive.
+ *
+ * It is advisory and best-effort: a crashed holder is reclaimed after `staleMs`
+ * with no heartbeat. The lock SHRINKS the race window; the `tokenGen` generation
+ * guard in `refresh.ts` is the data-level backstop that keeps the residual window
+ * safe (a superseded refresher adopts the winner's token instead of disabling).
+ */
+/** Tunable lock timing. All values in ms. */
+export interface LockOptions {
+    /** A held lock whose heartbeat has not advanced for this long is treated as crashed. */
+    readonly staleMs: number;
+    /** Give up acquiring after this long, throwing LockTimeoutError. */
+    readonly timeoutMs: number;
+    /** Base poll interval between acquisition attempts (jittered up to 2x). */
+    readonly retryMs: number;
+    /** Re-touch the held lock this often so a live holder never looks stale. */
+    readonly heartbeatMs: number;
+}
+interface LockHandle {
+    release(): Promise<void>;
+}
+export declare class LockTimeoutError extends Error {
+    readonly lockDir: string;
+    constructor(lockDir: string);
+}
+/** Acquire `lockDir`, waiting for a current holder up to `timeoutMs`. */
+export declare function acquireLock(lockDir: string, opts: LockOptions): Promise<LockHandle>;
+/** Run `fn` while holding `lockDir`, releasing it even if `fn` throws. */
+export declare function withLock<T>(lockDir: string, opts: LockOptions, fn: () => Promise<T>): Promise<T>;
+export {};

package/dist/pool/paths.d.ts

@@ -0,0 +1,16 @@
+interface DataDirEnv {
+    override?: string | undefined;
+    xdgDataHome?: string | undefined;
+}
+/**
+ * Resolve opencode's data directory, matching opencode-core's `xdg-basedir` usage:
+ *   $XDG_DATA_HOME/opencode  or  ~/.local/share/opencode
+ *
+ * xdg-basedir is platform-agnostic — it does NOT special-case Windows or macOS, so
+ * opencode uses ~/.local/share/opencode on every OS (verified with `opencode debug
+ * paths` on Windows). OPENCODE_AUTH_LB_DIR overrides everything (handy for tests).
+ */
+export declare function resolveDataDir(env: DataDirEnv, home: string): string;
+/** Path to the load-balancer's credential pool file. */
+export declare function poolFilePath(): string;
+export {};

package/dist/pool/store.d.ts

@@ -0,0 +1,51 @@
+import { type PoolAccount, type PoolFile } from '../types';
+/** Thrown when the pool file cannot be written atomically after retries. */
+export declare class PoolWriteError extends Error {
+    readonly path: string;
+    readonly reason: unknown;
+    constructor(path: string, reason: unknown);
+}
+/**
+ * Thrown when the pool file exists but cannot be READ (EACCES, EMFILE, Windows
+ * EBUSY/EPERM from an AV tool, EISDIR…). Deliberately distinct from the two
+ * tolerated read outcomes (missing file, corrupt JSON → empty pool): inside
+ * `mutatePool` a swallowed transient read fault would mutate an EMPTY pool and
+ * write it back — atomically WIPING every registered account. Bubbling a typed
+ * error lets `bestEffort` skip the bookkeeping write instead.
+ */
+export declare class PoolReadError extends Error {
+    readonly path: string;
+    readonly reason: unknown;
+    constructor(path: string, reason: unknown);
+}
+/** Injectable fs surface so the atomic-write fallback path is unit-testable. */
+export interface FsOps {
+    mkdir: (path: string, opts: {
+        recursive: boolean;
+    }) => Promise<unknown>;
+    writeFile: (path: string, data: string, opts: {
+        mode: number;
+    }) => Promise<void>;
+    rename: (from: string, to: string) => Promise<void>;
+    unlink: (path: string) => Promise<void>;
+}
+/**
+ * Write JSON atomically: temp file + rename (atomic on POSIX and modern Windows).
+ * If the rename fails — e.g. a concurrent process briefly holds the target open
+ * (Windows EPERM) — retry a few times, then clean up the temp file and throw. We
+ * never fall back to a direct overwrite: that sacrifices atomicity and can shred a
+ * concurrent writer's update. Mutations already run under the cross-process pool
+ * lock, so a sustained rename failure is a real disk fault worth surfacing.
+ */
+export declare function writeJsonAtomic(path: string, payload: string, ops?: FsOps): Promise<void>;
+/** Read the pool (serialized against in-flight mutations). */
+export declare function readPool(): Promise<PoolFile>;
+/**
+ * Atomically read-modify-write the pool. The callback mutates `pool` in place;
+ * its return value is forwarded to the caller.
+ */
+export declare function mutatePool<T>(fn: (pool: PoolFile) => T | Promise<T>): Promise<T>;
+/** Find an account by id within a pool object. */
+export declare function findAccount(pool: PoolFile, id: string): PoolAccount | undefined;
+/** Read a single account by id from the on-disk pool (serialized read). */
+export declare function readPoolAccount(id: string): Promise<PoolAccount | undefined>;

package/dist/prime.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Point the "in-use" marker at the top-ranked account for a provider. Startup is a
+ * clean-context moment — no session is pinned yet — so the next request will pick this
+ * account anyway; reflecting it immediately means the dashboard shows the account that
+ * will actually be used next, not whichever one happened to serve last. Best-effort.
+ *
+ * The selection is folded INTO the `mutatePool` callback so it runs against the
+ * just-locked pool snapshot we are about to write. That closes the small TOCTOU
+ * window between a prior `readPool()` and this write (another opencode process could
+ * re-rank, a cooldown could apply, or an account could be deleted via the TUI in
+ * between) and saves the extra read on the hot startup path. The `lastSelected`
+ * field is informational, so even with the old window the commit was benign — but
+ * the invariant is now local ("we commit the account selected from the SAME snapshot
+ * we are writing").
+ *
+ * NOTE: this lives in its own module (not exported from `index.ts`) on purpose —
+ * opencode's plugin loader treats EVERY function exported by the plugin entry module
+ * as a plugin and invokes it, so a stray exported helper there gets called with the
+ * plugin input and its `undefined` return poisons the hook list.
+ *
+ * Fast path (same pattern as `bootstrapFromOpencodeAuth`): both provider plugins
+ * run this at every opencode startup, so without it every start would take the
+ * in-process mutex + cross-process file lock and atomically rewrite the pool
+ * file byte-identically — `selectAccount` over zero accounts changes nothing,
+ * and in the steady state (every restart after the first request)
+ * `lastSelected` already points at the top-ranked account. One cheap serialized
+ * read skips all of those no-op writes. No TOCTOU concern: the fast path only
+ * skips a write that would change nothing, an account added concurrently is
+ * primed by its own login/startup flow, and `lastSelected` is informational
+ * anyway (see above).
+ */
+export declare function primeInUse(providerID: string, now: number): Promise<void>;

package/dist/providers/anthropic/adapter.d.ts

@@ -0,0 +1,8 @@
+import { type ProviderAdapter } from '../types';
+/**
+ * Anthropic (Claude Pro/Max OAuth) provider adapter.
+ *
+ * Login mode is fixed to "max" (subscription accounts) — the pool exists to
+ * balance subscription quota, not metered API keys.
+ */
+export declare const anthropicAdapter: ProviderAdapter;

package/dist/providers/anthropic/cch.d.ts

@@ -0,0 +1,20 @@
+interface Message {
+    role?: string;
+    content?: string | Array<{
+        type?: string;
+        text?: string;
+    }>;
+}
+/** Compute cch: first 5 hex characters of SHA-256(messageText). */
+export declare function computeCCH(messageText: string): string;
+/** Compute the 3-char version suffix from the sampled message characters. */
+export declare function computeVersionSuffix(text: string, version?: string): string;
+/**
+ * Build the complete billing header string for insertion into system[0], or
+ * null when no user-role message exists (the single prefix scan here is both
+ * the has-user-message gate and the text-extraction source).
+ * A user message that exists but yields empty text still produces a header.
+ * Closure-free loop (not Array.find) — runs once per Anthropic request.
+ */
+export declare function buildBillingHeaderValue(messages: (Message | null | undefined)[], entrypoint: string): string | null;
+export {};

package/dist/providers/anthropic/constants.d.ts

@@ -0,0 +1,64 @@
+export declare const PROVIDER_ID = "anthropic";
+export declare const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+export declare const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+export declare const CODE_CALLBACK_URL = "https://platform.claude.com/oauth/code/callback";
+export declare const TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+export { OAUTH_HTTP_TIMEOUT_MS, USAGE_HTTP_TIMEOUT_MS } from '../http-timeouts';
+/** Dedicated usage endpoint — returns 5h + 7d utilization without consuming quota. */
+export declare const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+export declare const OAUTH_SCOPES: string[];
+export declare const TOOL_PREFIX = "mcp_";
+/**
+ * LAST-RESORT downgrade target when a MODEL-TIER weekly cap is exhausted and
+ * the fallback LADDER cannot produce a candidate (the provider's model catalog
+ * is empty or has no model in a lower family). The normal path walks
+ * `DEFAULT_FAMILY_ORDER` through the catalog instead — see
+ * `ladderTargetForFamily`/`downgradeModel` in fallback.ts. Also the historic
+ * name of the override env (`OPENCODE_AUTH_LB_ANTHROPIC_OPUS_FALLBACK_MODEL`):
+ * set it to a model id to PIN the downgrade target (bypassing the ladder), or
+ * to an empty string to DISABLE downgrading (revert to cooling the whole
+ * account down).
+ */
+export declare const DEFAULT_OPUS_FALLBACK_MODEL = "claude-sonnet-4-6";
+/**
+ * Model FAMILIES best → worst: the fallback ladder for a tier-capped request
+ * walks this order strictly BELOW the limited model's family and picks the
+ * highest-versioned catalog model of the first family that has one (e.g. a
+ * capped `claude-fable-5` prefers `claude-opus-4-9` over `claude-opus-4-8`;
+ * if the whole Opus tier is capped too, the next pass lands on Sonnet). A
+ * family NOT in this list (a future top tier) is treated as ABOVE the first
+ * entry — new premium tiers historically appear at the top. Overridable via
+ * `OPENCODE_AUTH_LB_ANTHROPIC_FAMILY_ORDER` (comma-separated, best first) so
+ * future models need a config tweak, not a code change.
+ */
+export declare const DEFAULT_FAMILY_ORDER: readonly string[];
+/** 429 header naming which rate-limit window is the binding constraint. */
+export declare const REPRESENTATIVE_CLAIM_HEADER = "anthropic-ratelimit-unified-representative-claim";
+/**
+ * `representative-claim` values that name a MODEL-TIER window (a per-model
+ * weekly/5h cap, e.g. `seven_day_opus`, `seven_day_fable`) rather than an
+ * account-wide one (bare `five_hour` / `seven_day`). The capture group is the
+ * tier name — the key of `PoolAccount.modelCooldownsUntil`.
+ */
+export declare const MODEL_TIER_CLAIM_RE: RegExp;
+/** 429 header with the unix-seconds reset time of the binding window. */
+export declare const UNIFIED_RESET_HEADER = "anthropic-ratelimit-unified-reset";
+export declare const REQUIRED_BETAS: string[];
+export declare const OPENCODE_IDENTITY_PREFIX = "You are OpenCode";
+export declare const CLAUDE_CODE_IDENTITY = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+export declare const CCH_SALT = "59cf53e54c78";
+export declare const CCH_POSITIONS: number[];
+export declare const CLAUDE_CODE_VERSION = "2.1.87";
+export declare const CLAUDE_CODE_ENTRYPOINT = "sdk-cli";
+/** User-Agent for /v1/messages (matches the reference plugin's validated value). */
+export declare const USER_AGENT = "claude-cli/2.1.87 (external, cli)";
+/**
+ * User-Agent for the /api/oauth/usage endpoint. This endpoint hard-rejects
+ * (429) requests whose UA is not `claude-code/<version>`.
+ */
+export declare const USAGE_USER_AGENT = "claude-code/2.1.87";
+export declare const PARAGRAPH_REMOVAL_ANCHORS: string[];
+export declare const TEXT_REPLACEMENTS: {
+    match: string;
+    replacement: string;
+}[];

package/dist/providers/anthropic/fallback.d.ts

@@ -0,0 +1,52 @@
+import type { ModelFallback, ReactiveModelFallback } from '../types';
+/**
+ * The model FAMILY of a first-party model id — the tier name its per-model cap
+ * is keyed by: `claude-opus-4-7` → "opus", `claude-fable-5` → "fable",
+ * `claude-3-5-sonnet-latest` → "sonnet". The first alphabetic dash-segment
+ * after the vendor prefix; null when no such segment exists (unknown /
+ * non-first-party ids never participate in tier logic).
+ */
+export declare function modelFamily(model: string): string | null;
+/**
+ * The tier a request body asks for (the `modelCooldownsUntil` key to consult
+ * before sending), or null when the body is not JSON / has no string model /
+ * the model has no recognizable family.
+ */
+export declare function requestModelTier(body: string): string | null;
+export declare function resolveFamilyOrder(): readonly string[];
+/**
+ * How the downgrade target is chosen:
+ *  - `ladder` (env unset): walk the family order through the catalog.
+ *  - `pinned` (env = a model id): always that model, bypassing the ladder.
+ *  - `disabled` (env = empty/blank): no downgrade — account-wide cooldown.
+ */
+type FallbackSetting = {
+    kind: 'ladder';
+} | {
+    kind: 'pinned';
+    model: string;
+} | {
+    kind: 'disabled';
+};
+export declare function resolveFallbackSetting(): FallbackSetting;
+/**
+ * Rewrite a request body's `model` one rung down the fallback ladder (or to
+ * the pinned override). Returns the rewritten body (+ the from/to ids for the
+ * toast) or null when: the feature is disabled, the body is not JSON, `model`
+ * is absent/non-string/family-less, or the chosen target lands in the SAME
+ * family (a same-tier rewrite cannot escape that tier's cap — e.g. a
+ * Sonnet-tier 429 with no lower catalog family has no cheaper first-party
+ * target, so it falls through to the normal account cooldown). Callers gate
+ * on a cheap condition (a stored tier cooldown or a response header) BEFORE
+ * this parse.
+ */
+export declare function downgradeModel(body: string, models: readonly string[]): ModelFallback | null;
+/**
+ * REACTIVE: on a rejected response, when the binding limit is a MODEL-TIER cap
+ * (`representative-claim: seven_day_<tier>` / `five_hour_<tier>`) and the sent
+ * body's model can fall down the ladder, return the tier to persist, the tier
+ * reset, and the downgraded body (adopted only once the whole pool proves
+ * tier-limited). The header claim is checked BEFORE the body parse.
+ */
+export declare function planReactiveFallback(res: Response, body: string, now: number, models: readonly string[]): ReactiveModelFallback | null;
+export {};

package/dist/providers/anthropic/oauth.d.ts

@@ -0,0 +1,8 @@
+import type { TokenSet } from '../../types';
+import type { AuthorizeRequest } from '../types';
+/** Begin the PKCE authorization flow (Claude Pro/Max subscription accounts). */
+export declare function authorize(): Promise<AuthorizeRequest>;
+/** Exchange a pasted authorization code/URL for tokens. Returns null on failure. */
+export declare function exchange(input: string, verifier: string, redirectUri: string, expectedState?: string): Promise<TokenSet | null>;
+/** Refresh an access token. Throws on failure; message includes the HTTP status. */
+export declare function refresh(refreshToken: string): Promise<TokenSet>;

package/dist/providers/anthropic/transform.d.ts

@@ -0,0 +1,23 @@
+import { type FetchInput } from '../types';
+/** Merge incoming beta headers with the required OAuth betas, deduplicating. */
+export declare function mergeBetaHeaders(headers: Headers): string;
+/** Set OAuth auth + Claude Code headers; remove x-api-key (we use Bearer). */
+export declare function setOAuthHeaders(headers: Headers, accessToken: string): void;
+/**
+ * Strip the tool prefix from tool names in streaming response text.
+ *
+ * `alreadyScanned` marks a leading region of `text` that a PREVIOUS call
+ * already processed (createStrippedStream re-scans its retained tail together
+ * with each new chunk). A match ending inside that region can only be one
+ * RE-INTRODUCED by a prior replacement — a tool whose real name starts with
+ * `mcp_` (e.g. `mcp_Auth_lb_status` → stripped once to `"name": "mcp_..."`) —
+ * so it must be kept, not stripped a second time. A genuine pattern straddling
+ * the boundary ends AFTER `alreadyScanned` and is still replaced.
+ */
+export declare function stripToolPrefix(text: string, alreadyScanned?: number): string;
+/** Add ?beta=true for /v1/messages, and honor ANTHROPIC_BASE_URL overrides. */
+export declare function rewriteUrl(input: FetchInput): FetchInput;
+/** Rewrite the request body: sanitize system prompt, inject billing header, prefix tools. */
+export declare function rewriteRequestBody(body: string): string;
+/** Wrap a streaming response so tool prefixes are stripped from emitted text. */
+export declare function createStrippedStream(response: Response): Response;

package/dist/providers/anthropic/usage.d.ts

@@ -0,0 +1,14 @@
+import type { PoolAccount, UsageSnapshot } from '../../types';
+/**
+ * Parse usage from /v1/messages response headers (free, on every response).
+ * The parse itself (null-short-circuit, "no capturedAt", "`{}` collapses to
+ * null") lives in the shared `parseWindowPairHeaders` — only the header names
+ * and the fraction scale are Anthropic-specific.
+ */
+export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
+/**
+ * Poll the dedicated usage endpoint for authoritative 5h + 7d utilization without
+ * consuming inference quota. Returns null on any failure — including a 200 whose
+ * body is not the usage shape — so the caller keeps the last-known snapshot.
+ */
+export declare function fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;

package/dist/providers/headers.d.ts

@@ -0,0 +1,7 @@
+import type { FetchInput } from './types';
+/**
+ * Merge headers from a Request object and/or a RequestInit headers value into a
+ * single Headers instance. Provider-agnostic; used by the core fetch before
+ * handing the Headers to an adapter's applyAuth.
+ */
+export declare function mergeHeaders(input: FetchInput, init?: RequestInit): Headers;

package/dist/providers/http-timeouts.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HTTP timeout budgets shared by BOTH provider adapters. These are not
+ * provider-specific values that happen to coincide — the invariants they
+ * encode (stay below the refresh lock's stale window; bound fire-and-forget
+ * usage polls) apply identically to the Anthropic and OpenAI paths, so they
+ * are single-sourced here (like `pkce.ts` / `oauth-callback.ts` /
+ * `usage-http.ts`) and re-exported from each provider's `constants.ts`.
+ */
+/**
+ * Bound every OAuth token-endpoint call (exchange/refresh) so a hung network never
+ * holds the per-account refresh lock for its full stale window. Must stay below the
+ * refresh lock's stale timeout (120s) so the lock is released by the abort first.
+ */
+export declare const OAUTH_HTTP_TIMEOUT_MS = 30000;
+/**
+ * Bound every usage-endpoint poll so a hung usage server never accumulates
+ * fire-and-forget sockets. `fetchUsage` is called fire-and-forget from
+ * `refreshUsageInBackground`; the `lastPoll` throttle prevents same-account
+ * re-poll within SEED_TTL_MS but does NOT cancel an in-flight hung fetch.
+ * Symmetric with `OAUTH_HTTP_TIMEOUT_MS` (30 s).
+ */
+export declare const USAGE_HTTP_TIMEOUT_MS = 30000;
+/**
+ * Upper bound for any quota-reset-related duration derived from a response
+ * header (a `Retry-After` cooldown in `fetch.ts`, a tier `unified-reset` in
+ * `providers/anthropic/fallback.ts`). Both encode the same invariant: a real
+ * quota window is at most weekly (≤ 7 days), so anything past this bound is a
+ * broken server/proxy clock and must be rejected — falling through to the
+ * caller's short self-healing default — instead of sidelining an account (or
+ * downgrading a model tier) for years on a bogus far-future value.
+ */
+export declare const MAX_QUOTA_RESET_BOUND_MS: number;

package/dist/providers/oauth-callback.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared OAuth callback helpers used by both the Anthropic and OpenAI OAuth
+ * flows. Sibling to `pkce.ts` — both providers had near-identical private
+ * copies of `generateState` (byte-identical) and `parseCallbackInput`
+ * (95%-identical: the Anthropic variant also accepts the legacy `code#state`
+ * hash-split format pasted manually by users). Keeping two copies meant every
+ * future tweak (new callback format, whitespace normalization) had to be made
+ * in two places to stay consistent. `readTokenResponse` unifies the same way:
+ * the token-endpoint 200-body validation was copy-pasted four times (exchange
+ * + refresh, per provider). `toTokenSet` single-sources the response→TokenSet
+ * mapping contract the same way — it too was maintained as two mirrored
+ * private copies.
+ */
+import type { TokenSet } from '../types';
+/** The fields every provider's token-endpoint response must carry. */
+export interface BaseTokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+}
+/**
+ * Map a token-endpoint response body to a TokenSet. RFC 6749 §5.1: the server
+ * MAY omit refresh_token; fall back to `previousRefresh` then — `''` at
+ * exchange time (no previous token; a missing field still fails the next
+ * refresh loudly, but never writes `undefined` onto the pool account), the
+ * current token at refresh time. Providers with extra fields (e.g. OpenAI's
+ * `accountId`) spread this result and add them.
+ */
+export declare function toTokenSet(json: BaseTokenResponse, previousRefresh: string): TokenSet;
+/**
+ * Parse and validate an OAuth token-endpoint 200 body. Returns null when the
+ * body is not JSON, `access_token` is missing/empty, `expires_in` is
+ * missing, or a PRESENT, non-null `refresh_token` is non-string — otherwise
+ * a SyntaxError escapes into the login flow, an empty-string `access_token`
+ * writes `access: ''` onto the pool row (silently bricking auth until the
+ * next self-healing refresh), a missing `expires_in` poisons the pool with
+ * `expires: NaN` (which `needsRefresh` never treats as stale), or a
+ * malformed `refresh_token` (e.g. a number) writes a non-string value onto
+ * `PoolAccount.refresh` (typed `string`) via `toTokenSet`'s
+ * `json.refresh_token || previousRefresh` — until the next `readPool()`
+ * heals it via `normalizeAccounts`'s own `typeof row.refresh !== 'string'`
+ * guard (`pool/store.ts`). `refresh_token` is still OPTIONAL per RFC 6749
+ * §5.1 — only a present-but-wrong-type value is rejected. An explicit JSON
+ * `null` (how some statically-typed token endpoints serialize an omitted
+ * `Option<String>`) is treated the same as `undefined`: both are falsy, so
+ * `toTokenSet`'s `json.refresh_token || previousRefresh` already falls back
+ * identically for either — rejecting `null` here would just misreport a
+ * valid response as "malformed" for no behavioral gain.
+ * `expires_in` must be FINITE, not just a number: `JSON.parse('1e999')`
+ * legally yields `Infinity`, which would poison the pool with
+ * `expires: Infinity` — the same never-stale soft-brick as NaN.
+ * It must also be POSITIVE: RFC 6749 §5.1 defines it as a lifetime in
+ * seconds, so 0/negative is nonsensical — and would write an already-expired
+ * `expires` to the pool, making `needsRefresh` true on EVERY request (a
+ * network refresh round-trip per request, each burning a single-use rotated
+ * refresh token).
+ * Its MS PRODUCT must be finite too: a finite-but-huge value like `1e306`
+ * passes the checks above, yet every consumer computes
+ * `Date.now() + expires_in * 1000`, and `1e306 * 1000` collapses to
+ * `+Infinity` — the same never-stale soft-brick. Mirrors the `secondsToMs`
+ * guard in `src/util.ts` and `cooldownUntilFrom`'s retry-after guard in
+ * `src/fetch.ts`.
+ * Callers decide the failure shape: exchange sites return null, refresh sites
+ * throw their status-prefixed "malformed token response body" error.
+ */
+export declare function readTokenResponse<T extends BaseTokenResponse = BaseTokenResponse>(res: Response): Promise<T | null>;
+/**
+ * Validate an exchange-endpoint response with the shared exchange failure
+ * contract: null on a non-ok status (with the body stream — and its HTTP
+ * connection — released), null on a malformed 200 body (see
+ * readTokenResponse). Refresh-side sibling of `readRefreshResponse`; both
+ * providers' `exchange` delegate here so a future tweak (logging, a new
+ * failure shape) can never be made in only one copy.
+ */
+export declare function readExchangeResponse<T extends BaseTokenResponse = BaseTokenResponse>(res: Response): Promise<T | null>;
+/**
+ * Validate a refresh-endpoint response, throwing the status-prefixed error
+ * `isInvalidGrant()` (src/refresh.ts) parses — that message format is a
+ * contract, single-sourced here so it can never be half-updated. A malformed
+ * 200 body must never reach commitRefresh, or the account gets `expires: NaN`
+ * (which needsRefresh never treats as stale) and soft-bricks into a perpetual
+ * auth-cooldown loop that survives restarts; the 200-status prefix keeps
+ * isInvalidGrant() false (200 ≠ 400/401), so the failure stays transient —
+ * the account is NOT disabled.
+ */
+export declare function readRefreshResponse<T extends BaseTokenResponse = BaseTokenResponse>(res: Response): Promise<T>;
+/** Generate an opaque OAuth `state` parameter (32-char hex, no hyphens). */
+export declare function generateState(): string;
+/**
+ * Parse a pasted OAuth callback into `{ code, state }`. Accepts a full
+ * `https://…?code=…&state=…` URL, a `key=value` form (`code=…&state=…`), and
+ * — when `allowHashFormat` is on — the legacy/manual `<code>#<state>` format.
+ * Returns null when no shape matches.
+ */
+export declare function parseCallbackInput(input: string, options?: {
+    allowHashFormat?: boolean;
+}): {
+    code: string;
+    state: string;
+} | null;

package/dist/providers/openai/adapter.d.ts

@@ -0,0 +1,9 @@
+import { type ProviderAdapter } from '../types';
+/**
+ * OpenAI ChatGPT/Codex (subscription OAuth) provider adapter.
+ *
+ * Assumes opencode's `openai` provider is configured to use the Responses API
+ * (the standard ChatGPT/Codex setup) — requests on a `/responses` path are routed
+ * to the Codex backend. Other paths are left untouched.
+ */
+export declare const openaiAdapter: ProviderAdapter;

package/dist/providers/openai/constants.d.ts

@@ -0,0 +1,18 @@
+export declare const PROVIDER_ID = "openai";
+export declare const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
+export declare const TOKEN_URL = "https://auth.openai.com/oauth/token";
+export declare const REDIRECT_URI = "http://localhost:1455/auth/callback";
+export { OAUTH_HTTP_TIMEOUT_MS, USAGE_HTTP_TIMEOUT_MS } from '../http-timeouts';
+export declare const OAUTH_SCOPES: string[];
+/** ChatGPT-OAuth Codex inference endpoint. */
+export declare const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+/** Dedicated usage endpoint for ChatGPT OAuth (no inference required). */
+export declare const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+/** User-Agent for the usage endpoint — the Codex CLI sends `codex-cli`. */
+export declare const USAGE_USER_AGENT = "codex-cli";
+export declare const ORIGINATOR = "opencode";
+export declare const OPENAI_BETA = "responses=experimental";
+export declare const USER_AGENT: string;
+/** Stable per-process session id sent as the `session-id` header. */
+export declare const SESSION_ID: `${string}-${string}-${string}-${string}-${string}`;

package/dist/providers/openai/jwt.d.ts

@@ -0,0 +1,5 @@
+import type { PoolAccount } from '../../types';
+/** Extract the ChatGPT account id from an id_token, checking all known claim paths. */
+export declare function extractAccountId(idToken: string): string | undefined;
+/** Stored ChatGPT account id, or one decoded from the access-token JWT. */
+export declare function resolveAccountId(account: PoolAccount): string | undefined;

package/dist/providers/openai/oauth.d.ts

@@ -0,0 +1,12 @@
+import type { TokenSet } from '../../types';
+import type { AuthorizeRequest } from '../types';
+/** Begin the ChatGPT PKCE authorization flow. */
+export declare function authorize(): Promise<AuthorizeRequest>;
+/**
+ * Exchange a pasted callback URL (or `code#state`) for tokens. Returns null on
+ * failure. The redirect lands on http://localhost:1455/auth/callback — the user
+ * copies that URL from the browser address bar and pastes it here.
+ */
+export declare function exchange(input: string, verifier: string, redirectUri: string, expectedState?: string): Promise<TokenSet | null>;
+/** Refresh an access token. Throws on failure; message includes the HTTP status. */
+export declare function refresh(refreshToken: string): Promise<TokenSet>;

package/dist/providers/openai/transform.d.ts

@@ -0,0 +1,18 @@
+import type { PoolAccount } from '../../types';
+import { type FetchInput } from '../types';
+/**
+ * Codex (ChatGPT-OAuth) request shaping, distilled from the openai/codex CLI,
+ * anomalyco/opencode's codex plugin, and the openresponses Go middleware.
+ */
+/** Set OAuth auth + Codex headers; drop the SDK's dummy key/x-api-key. */
+export declare function applyAuth(headers: Headers, account: PoolAccount): void;
+/** Rewrite Responses-API requests to the Codex backend; leave others untouched. */
+export declare function rewriteUrl(input: FetchInput): FetchInput;
+/**
+ * Apply the mandatory Codex backend body quirks:
+ *   - store: false                 (backend rejects true)
+ *   - include += reasoning.encrypted_content  (preserve CoT across turns)
+ *   - non-empty instructions
+ *   - drop max_output_tokens       (match codex cli)
+ */
+export declare function rewriteRequestBody(body: string): string;

package/dist/providers/openai/usage.d.ts

@@ -0,0 +1,16 @@
+import type { PoolAccount, UsageSnapshot } from '../../types';
+/**
+ * Parse usage from Codex response headers (x-codex-{primary,secondary}-*).
+ * primary = ~5h window (hourly), secondary = weekly window. The parse itself
+ * (null-short-circuit, "no capturedAt", "`{}` collapses to null") lives in the
+ * shared `parseWindowPairHeaders` — only the header names and the percent
+ * scale are Codex-specific.
+ */
+export declare function parseUsageHeaders(headers: Headers): Partial<UsageSnapshot> | null;
+/**
+ * Poll GET /wham/usage for authoritative 5h (primary) + weekly (secondary)
+ * utilization without consuming inference quota. Null on failure. Sends the Codex
+ * CLI's `codex-cli` UA and the `chatgpt-account-id` (from the stored id or, as a
+ * fallback, decoded from the access-token JWT) — required for team/workspace accounts.
+ */
+export declare function fetchUsage(account: PoolAccount, now: number): Promise<UsageSnapshot | null>;

package/dist/providers/pkce.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared PKCE (RFC 7636) helper used by both the Anthropic and OpenAI OAuth
+ * flows (the per-provider copies were byte-identical). Only the S256 method is
+ * supported; both consumers hard-code `code_challenge_method=S256` into their
+ * URL params, so the method is not part of the return shape.
+ */
+export declare function generatePKCE(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;