@cortexkit/opencode-openai-auth 0.8.0 → 0.9.1

package/dist/internal-BTndPmW2.d.ts

@@ -0,0 +1,914 @@
+import { Endpoint } from "@cortexkit/subc-client";
+//#region ../../node_modules/.bun/@cortexkit+claustrum-client@0.3.0/node_modules/@cortexkit/claustrum-client/dist/detect.d.ts
+type ClaustrumEndpoint = Endpoint;
+type ClaustrumDetection = {
+  status: 'available';
+  schema: number;
+  wireVersion: number;
+  endpoints: ClaustrumEndpoint[];
+} | {
+  status: 'absent';
+  path: string;
+} | {
+  status: 'malformed';
+  path: string;
+  reason: string;
+};
+declare function detectClaustrumConnection(explicitPath?: string): Promise<ClaustrumDetection>;
+//#endregion
+//#region ../../node_modules/.bun/@cortexkit+claustrum-client@0.3.0/node_modules/@cortexkit/claustrum-client/dist/handles.d.ts
+type HandleAccount = {
+  label: string;
+  handle: string;
+  credential_id: string;
+  superseded?: string[];
+  minTtlMs?: number;
+};
+type HandleProvider = {
+  provider: string;
+  shape: 'api' | 'oauth';
+  serve: string;
+  accounts: HandleAccount[];
+};
+type OpenCodeHandleFileV1 = {
+  version: 1;
+  providers: HandleProvider[];
+};
+//#endregion
+//#region ../../node_modules/.bun/@cortexkit+claustrum-client@0.3.0/node_modules/@cortexkit/claustrum-client/dist/manifest-lock.d.ts
+type ManifestHandleFile = OpenCodeHandleFileV1;
+//#endregion
+//#region ../core/dist/provider.d.ts
+type QuotaWindowName = string;
+type ProviderQuotaFn = (input: {
+  accessToken: string;
+  fetchImpl: typeof fetch;
+  now: () => number;
+}) => Promise<OAuthQuotaSnapshot>;
+//#endregion
+//#region ../core/dist/quota-manager.d.ts
+type QuotaEntry = {
+  quota: OAuthQuotaSnapshot;
+  refreshAfter: number;
+  checkedAt: number;
+  accountId?: string;
+};
+type QuotaManagerOptions = {
+  storage: AccountStorage | null;
+  fetchImpl?: typeof fetch;
+  /**
+   * Account config file this manager's cross-process refresh locks are named
+   * after. Host-resolved and required, so two hosts pointing at different
+   * stores never contend on one another's lock.
+   */
+  configPath: string;
+  now?: () => number;
+  /** Injected quota-fetch function — replaces the hard-imported Anthropic fetchOAuthQuotaSnapshot */
+  fetchQuotaFn?: ProviderQuotaFn;
+  onMainQuotaFetched?: (quota: OAuthQuotaSnapshot, checkedAt: number, fingerprint: string, fetchStartedAt: number) => void;
+  onApiError?: (error: AccountOperationError) => void;
+};
+declare class QuotaManager {
+  private main;
+  private mainTokenFp;
+  private mainQuotaAccountId;
+  private fallbacks;
+  private fallbackTokenFps;
+  private inflightMain;
+  private inflightMainFp;
+  private inflightFallbacks;
+  private mainLastApiError;
+  private fallbackApiErrors;
+  private fallbackErrorTokenFps;
+  private rateLimitedUntilMap;
+  private apiGate;
+  private lastApiCallAt;
+  private storage;
+  private readonly fetchImpl;
+  private readonly now;
+  private readonly fetchQuotaFn;
+  private readonly onMainQuotaFetched;
+  private readonly onApiError;
+  private readonly configPath;
+  constructor(opts: QuotaManagerOptions);
+  /**
+   * Cached main quota entry. Pass the live access token to enforce token
+   * binding: if the cached entry was produced by a different token (main
+   * account switched), it is dropped and null is returned so the caller
+   * refetches for the current account. Called without a token (e.g. for
+   * display) it returns whatever is cached.
+   */
+  getMain(accessToken?: string): QuotaEntry | null;
+  /**
+   * Cached fallback quota entry. Pass the live access token to enforce token
+   * binding: if the entry was produced by a different token (account re-login),
+   * it is dropped and null is returned so the caller refetches.
+   */
+  getFallback(accountId: string, accessToken?: string): QuotaEntry | null;
+  getAllFallbacks(): Map<string, QuotaEntry>;
+  setMain(accessToken: string, entry: QuotaEntry, accountId?: string, completeSnapshot?: boolean): void;
+  /**
+   * Non-invalidating read of the cached main quota for POLICY decisions
+   * (killswitch). Unlike getMain(token), a token mismatch does NOT drop the
+   * cache — an access-token refresh is a same-account event and must not turn a
+   * known-exhausted account into "unknown" (which would fail open and spend).
+   *
+   * Pass the live ChatGPT accountId to still drop on a genuine account SWITCH:
+   * if the cached entry's account identity is known and differs, return null so
+   * the killswitch treats it as unknown rather than judging account A by account
+   * B's quota. When identity is unknown on either side, the cached snapshot is
+   * returned (best-effort) — the same fail-open-on-unknown stance as elsewhere.
+   */
+  peekMainForPolicy(accountId?: string): QuotaEntry | null;
+  /**
+   * Non-invalidating read of a cached fallback quota for POLICY decisions
+   * (killswitch, admission). Keyed by the stable internal account id, so a
+   * token refresh for the same account does not drop it (getFallback(id, token)
+   * would).
+   *
+   * Pass the live ChatGPT identity to still drop on a genuine re-login: if the
+   * cached entry's identity is known and differs, return null so the previous
+   * identity's (possibly exhausted) quota is never judged against its
+   * replacement. Unknown on either side fails open, matching peekMainForPolicy.
+   */
+  peekFallbackForPolicy(accountId: string, identity?: string): QuotaEntry | null;
+  setFallback(accountId: string, entry: QuotaEntry, accessToken?: string, completeSnapshot?: boolean, identity?: string): void;
+  /**
+   * Mark accountId ('main' or a fallback id) rate-limited until resetAtMs.
+   * Keeps the LATER reset: skips only when an existing mark is strictly
+   * later than resetAtMs, so an equal-reset re-mark still applies (idempotent)
+   * instead of being silently dropped by a stale `>=` comparison.
+   */
+  markRateLimited(accountId: string, resetAtMs: number): void;
+  /** True iff accountId has a mark whose reset has not yet passed. */
+  isRateLimited(accountId: string): boolean;
+  /**
+   * Raw stored reset for accountId's mark, or undefined if none. Unlike
+   * isRateLimited, this does NOT apply read-time expiry — callers on the
+   * block path already know the mark is live (isRateLimited just returned
+   * true) and want its exact reset estimate for a Retry-After computation.
+   */
+  rateLimitedUntil(accountId: string): number | undefined;
+  /** Explicit early clear — read-time expiry in isRateLimited is primary. */
+  clearRateLimited(accountId: string): void;
+  refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
+  refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
+  refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
+  /**
+   * Fire-and-forget refresh. Does not await, swallows errors.
+   */
+  refreshMainInBackground(accessToken: string): void;
+  isMainStale(): boolean;
+  isFallbackStale(accountId: string, accessToken?: string): boolean;
+  shouldRefreshOnRequestCount(requestCount: number): boolean;
+  /**
+   * Combined check: should a refresh happen right now?
+   * True if main is stale by time OR triggered by request count.
+   */
+  needsRefresh(requestCount: number): boolean;
+  updateStorage(storage: AccountStorage | null): void;
+  /**
+   * Seed/update the main quota cache from persisted state. This is deliberately
+   * callable after every disk load so another plugin process's fresh quota write
+   * can stop this process from showing "checking…" or making a redundant quota
+   * API call.
+   */
+  seedMainFromStorage(storage: AccountStorage | null, accessToken?: string): void;
+  private seedMainBackoffFromStorage;
+  /**
+   * Seed fallback cache entries from persisted account.quota data.
+   * Updates older in-memory entries so a fresh quota write from another plugin
+   * process prevents redundant checks and stale sidebar writes.
+   */
+  seedFallbacksFromAccounts(accounts: OAuthAccount[]): void;
+  /**
+   * Whether the MAIN quota API is currently in backoff. Scoped to the main
+   * account — a fallback account's 429 never reports here.
+   */
+  isBackedOff(): boolean;
+  /**
+   * Whether a specific fallback account's quota API is in backoff.
+   */
+  isFallbackBackedOff(accountId: string, accessToken?: string): boolean;
+  getLastApiError(): AccountOperationError | undefined;
+  /** Minimum gap between consecutive quota API calls (ms). */
+  private static readonly API_CALL_GAP_MS;
+  private static fallbackInflightKey;
+  private static quotaLockName;
+  /**
+   * Serialize API calls through a shared gate so only one
+   * quota API request runs at a time, with a minimum gap
+   * between calls. Prevents concurrent and rapid-fire calls
+   * from triggering rate limits.
+   */
+  private _enqueueApiFetch;
+  private _fetchMain;
+  private _fetchFallback;
+  /** Route through injected fetchQuotaFn, or throw if unset. */
+  private _fetchQuota;
+  private static isAuthError;
+  /** Main quota failure: arms main-only backoff and persists via onApiError. */
+  private _handleMainFetchError;
+  /**
+   * Fallback quota failure: arms backoff for THIS account only. Never touches
+   * main backoff state and never calls onApiError (which persists the main
+   * quota error) — the per-account error is recorded by the caller via the
+   * account's lastQuotaRefreshError.
+   */
+  private _handleFallbackFetchError;
+}
+//#endregion
+//#region ../core/dist/custody-manifest.d.ts
+type CustodyManifestReadResult = {
+  ok: true;
+  value: ManifestHandleFile;
+  revision: string;
+} | {
+  ok: false;
+  reason: 'absent';
+} | {
+  ok: false;
+  reason: 'tooLarge';
+  message: string;
+} | {
+  ok: false;
+  reason: 'permissions' | 'unsafeParent' | 'notRegular' | 'symlink';
+  message: string;
+} | {
+  ok: false;
+  reason: 'invalid';
+  message: string;
+} | {
+  ok: false;
+  reason: 'unreadable';
+  message: string;
+};
+type CustodyManifestIo = {
+  lstat?: (path: string) => Promise<CustodyStat>;
+  stat?: (path: string) => Promise<CustodyStat>;
+  readFile?: (path: string, encoding: 'utf8') => Promise<string>;
+  open?: (path: string) => Promise<CustodyDescriptor>;
+  currentUid?: () => number | undefined;
+};
+type CustodyStat = {
+  isFile(): boolean;
+  isDirectory?(): boolean;
+  isSymbolicLink?(): boolean;
+  mode: number;
+  size?: number;
+  uid?: number;
+  mtimeMs?: number;
+};
+type CustodyDescriptor = {
+  stat(): Promise<CustodyStat>;
+  read(options: {
+    buffer: Buffer;
+    offset: number;
+    length: number;
+    position: number;
+  }): Promise<{
+    bytesRead: number;
+  }>;
+  close(): Promise<void>;
+};
+//#endregion
+//#region ../core/dist/refresh-file-lock.d.ts
+declare function acquireRefreshFileLock(options: {
+  name: string;
+  ttlMs: number;
+  /**
+   * File the lock is named after. Required: the lock and the write it guards
+   * must target the same file, and a default resolved in here could only ever
+   * be one host's path.
+   */
+  path: string;
+  now?: () => number;
+  renew?: boolean;
+  renewIntervalMs?: number;
+  onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+}): Promise<{
+  release: () => Promise<void>;
+} | null>;
+//#endregion
+//#region ../core/dist/custody.d.ts
+type ClaustrumMode = 'local' | 'claustrum';
+type CustodyTransitionState = {
+  manifestRevision: string;
+  storeGeneration: string;
+  fingerprints: {
+    main?: string;
+    fallbacks: Record<string, string>;
+  };
+};
+declare const CUSTODY_REFUSE: unique symbol;
+declare const CUSTODY_EXCLUDED: unique symbol;
+type VaultProvenance = {
+  handle: string;
+  recordVersion: number;
+};
+type FallbackAccessResolution = {
+  token: string;
+  provenance: 'local';
+} | {
+  token: string;
+  provenance: VaultProvenance;
+};
+type ResolveFallbackAccessOptions = {
+  cache?: ClaustrumCredentialCache;
+  manifestHandle?: string;
+  completeEnrollmentDeps?: CompleteEnrollmentDeps;
+  refreshBeforeExpiryMs?: number;
+  now?: () => number;
+  requestPath?: boolean;
+};
+declare function resolveFallbackAccess(account: OAuthAccount, storage: Pick<AccountStorage, 'claustrum'>, manifest?: CustodyManifestReadResult, options?: ResolveFallbackAccessOptions): Promise<FallbackAccessResolution | typeof CUSTODY_REFUSE | typeof CUSTODY_EXCLUDED>;
+type ClaustrumCredentialCacheOptions = {
+  connector: (options: {
+    connectionFile: string;
+    handshakeTimeoutMs?: number;
+  }) => Promise<ClaustrumCacheTransport>;
+  now?: () => number;
+};
+type ClaustrumCacheTransport = {
+  getCredential(handle: string, minTtlMs?: number): Promise<{
+    material: string;
+    recordVersion: number;
+    expiresAtMs: number | null;
+    accountId?: string;
+  }>;
+  statusCredential(handle: string): Promise<{
+    ready: boolean;
+    lastErrorCode: string | null;
+    leaseHeld: boolean;
+    recordVersion: number;
+  }>;
+  reportAuthFailure(params: {
+    handle: string;
+    providerStatus: number;
+    recordVersion: number;
+    reporterSource: 'direct' | 'relay_status_field' | 'relay_message_parse';
+  }): Promise<void>;
+  close(): void;
+};
+type ResidentRecord = {
+  payload: {
+    access: string;
+  };
+  recordVersion: number;
+  expiresAtMs: number;
+  servedAccountId?: string;
+};
+declare class ClaustrumCredentialCache {
+  #private;
+  constructor(options: ClaustrumCredentialCacheOptions);
+  /**
+   * Peek the resident record without I/O. Returns `undefined` if absent,
+   * including the case where the record was invalidated by `reportAuthFailure`.
+   */
+  peek(handle: string): Promise<ResidentRecord | undefined>;
+  /**
+   * Public read-only view of a peek result. Exposes only the version and
+   * expiry — never the credential material — so a projection layer can
+   * surface a vault `recordVersion` without ever seeing a token.
+   */
+  peekMetadata(handle: string): Promise<{
+    recordVersion: number;
+    expiresAtMs: number;
+  } | undefined>;
+  /**
+   * True iff a recent auth failure on this handle has been reported to the
+   * daemon. The blocked set is informational; the resolver still attempts a
+   * fetch on `get`, which clears the flag on success.
+   */
+  isBlocked(handle: string): boolean;
+  /**
+   * True iff the bound-and-reauth fence has fired for this handle and the
+   * reauth window has not yet elapsed. Callers that project "needs reauth"
+   * UI should gate on this. The fence clears after a proven 2xx vault request
+   * or when the reauth window expires.
+   */
+  isReauth(handle: string, now?: number): boolean;
+  markVaultSuccess(handle: string): void;
+  /**
+   * Get the live resident record. If a live record exists and the caller
+   * did not pass `force:true`, it returns immediately (no daemon I/O).
+   * Otherwise it issues a single-flight `getCredential` call.
+   *
+   * `force:true` ALWAYS issues a new daemon call (it bypasses both the
+   * resident record and any pending in-flight that originated from a
+   * non-force caller). Two concurrent force:true calls share the same
+   * new in-flight promise, so the second and subsequent force:true verifies
+   * collapse onto the first one. A non-force caller issued while a
+   * force:true fetch is pending still joins that force-fetch in-flight —
+   * the cache never races two parallel daemon calls for the same handle.
+   */
+  get(handle: string, minTtlMs?: number, options?: {
+    force?: boolean;
+  }): Promise<ResidentRecord>;
+  /**
+   * Report an upstream auth failure on a served record. The report is
+   * version-fenced (one report per handle per recordVersion), and after
+   * two reports on the same version a one-hour bound fires — the third
+   * and subsequent reports on the same version are suppressed, and the
+   * handle is moved into the `reauth` set for an hour. A proven 2xx vault
+   * request or expiry of that window clears the bound and reauth entry.
+   *
+   * The reported version is invalidated from the resident record in
+   * `finally`, so a follow-up `get` cannot accidentally serve the same
+   * version the daemon already rejected.
+   */
+  reportAuthFailure(params: {
+    handle: string;
+    providerStatus: number;
+    recordVersion: number;
+  }): Promise<void>;
+  close(): void;
+}
+type CompleteEnrollmentDeps = {
+  loadAccounts: typeof loadAccounts;
+  readCustodyManifest: (path?: string) => Promise<CustodyManifestReadResult>;
+  acquireRefreshFileLock: typeof acquireRefreshFileLock;
+  configPath: string;
+  paths: AccountPaths;
+  manifestPath?: string;
+  cache: ClaustrumCredentialCache;
+  /** Minimum TTL (ms) handed to the vault for the verify-get. */
+  minTtlMs: number;
+  /**
+   * Read-modify-write the account store. The sweep calls this once on a
+   * successful verify, setting empty `access`, sentinel `refresh`, and
+   * `expires = 0` — that single write is the only durable effect.
+   */
+  mutateAccounts: typeof mutateAccounts;
+  /** Provider name; defaults to the owning provider (openai). */
+  provider?: string;
+  /** Caller-supplied clock so tests can drive the boot/hour log dedupe. */
+  now?: () => number;
+};
+//#endregion
+//#region ../core/dist/paths.d.ts
+/**
+ * The config file and the runtime-state file a store operation reads and writes.
+ *
+ * Both are required. A store function never derives one from the other, because
+ * a host may point its state file somewhere the derivation would not reach and
+ * a silently derived path would lock one file while writing another.
+ */
+interface AccountPaths {
+  configPath: string;
+  statePath: string;
+}
+//#endregion
+//#region ../core/dist/accounts.d.ts
+type AccountQuotaWindow = {
+  usedPercent: number;
+  remainingPercent: number;
+  resetsAt?: string;
+  checkedAt: number;
+  windowMinutes?: number;
+};
+interface OAuthQuotaSnapshot {
+  primary?: AccountQuotaWindow;
+  secondary?: AccountQuotaWindow;
+  resetCreditsAvailable?: number;
+  resetCreditsApplicable?: number;
+  spendControl?: OAuthSpendControlReading;
+  /**
+   * Set when the source explicitly reported that the account has no credit
+   * budget (wham's `spend_control` or `individual_limit` is null). An absent
+   * `spendControl` alone only means the source did not carry the field: header
+   * and WebSocket pushes never do, so merges keep the previous budget for them.
+   * This marker is what lets a merge drop a budget that no longer exists.
+   */
+  spendControlCleared?: true;
+  credits?: OAuthCredits;
+}
+interface OAuthSpendControlReading {
+  limit: number;
+  used: number;
+  remaining: number;
+  usedPercent: number;
+  remainingPercent: number;
+  resetsAt?: string;
+  unit?: string;
+  source?: string;
+  reached: boolean;
+}
+interface OAuthCredits {
+  hasCredits: boolean;
+  unlimited: boolean;
+  overageLimitReached: boolean;
+  balance?: number;
+}
+type AccountBase = {
+  id: string;
+  label?: string;
+  enabled?: boolean;
+  addedAt?: number;
+  lastUsed?: number;
+  /** Stable ChatGPT account identifier extracted from the OAuth token claims. */
+  accountId?: string;
+};
+type AccountOperationError = {
+  message: string;
+  checkedAt: number;
+  nextRetryAt?: number;
+  retryCount?: number;
+  tokenHash?: string;
+};
+type OAuthAccount = AccountBase & {
+  type: 'oauth';
+  corrupt?: false;
+  access?: string;
+  refresh: string;
+  expires?: number;
+  lastRefreshedAt?: number;
+  lastRefreshError?: AccountOperationError;
+  lastQuotaRefreshError?: AccountOperationError;
+  quota?: OAuthQuotaSnapshot;
+};
+type CorruptOAuthAccount = AccountBase & {
+  type: 'oauth';
+  corrupt: true;
+  access?: undefined;
+  refresh?: undefined;
+  expires?: undefined;
+  lastRefreshedAt?: undefined;
+  lastRefreshError?: undefined;
+  lastQuotaRefreshError?: undefined;
+  quota?: undefined;
+};
+type ApiKeyAccount = AccountBase & {
+  type: 'api';
+  apiKey?: string;
+  baseURL: string;
+  authHeader?: 'authorization-bearer' | 'x-api-key';
+};
+type FallbackAccount = OAuthAccount | CorruptOAuthAccount | ApiKeyAccount;
+type RoutingMode = 'main-first' | 'fallback-first' | 'sticky-balanced';
+type KillswitchThresholds = Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
+type KillswitchConfig = {
+  enabled?: boolean;
+  main?: KillswitchThresholds;
+  accounts?: Record<string, KillswitchThresholds>;
+};
+interface ResetInFlight {
+  redeemRequestId: string;
+  creditId: string;
+  startedAt: number;
+}
+interface ResetLastOutcome {
+  code: string;
+  at: number;
+  previousOutcome?: {
+    code: string;
+    at: number;
+  };
+}
+interface ResetAccountState {
+  inFlight?: ResetInFlight | Record<string, unknown>;
+  lastOutcome?: ResetLastOutcome;
+  cooldownUntil?: number;
+}
+type ResetStateByAccount = Record<string, ResetAccountState>;
+type AccountStorage = {
+  version: 1;
+  main?: {
+    type: 'opencode';
+    provider: 'openai';
+  };
+  routing?: {
+    mode?: RoutingMode;
+  };
+  fallbackOn?: number[];
+  refresh?: {
+    enabled?: boolean;
+    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;
+    mainQuota?: OAuthQuotaSnapshot;
+    mainQuotaCheckedAt?: number;
+    mainQuotaToken?: string;
+    mainLastQuotaApiError?: AccountOperationError;
+  };
+  reset?: ResetStateByAccount;
+  dump?: {
+    enabled?: boolean;
+  };
+  costZeroing?: {
+    enabled?: boolean;
+  };
+  killswitch?: KillswitchConfig;
+  logging?: {
+    level?: string;
+  };
+  cachekeep?: {
+    enabled?: boolean;
+    subagents?: boolean;
+    sustain?: boolean;
+    /** Clock-hour window start (0-23, inclusive) — keeps cachekeep idle warming
+     *  inside `[startHour, endHour)` local hours. Omit to warm unconditionally. */
+    startHour?: number;
+    /** Clock-hour window end (0-23, exclusive) — must differ from startHour
+     *  to be honored; an unset or equal hour falls back to "always warm". */
+    endHour?: number;
+  };
+  /** Stable ChatGPT account identifier of the main account (extracted from OAuth token). */
+  mainAccountId?: string;
+  claustrum?: {
+    mode?: ClaustrumMode;
+    transition?: CustodyTransitionState;
+    rowHistory?: string[];
+  };
+  accounts: FallbackAccount[];
+};
+declare function loadAccounts(paths: AccountPaths): Promise<AccountStorage | null>;
+type AccountStoreTransaction = {
+  read(): Promise<AccountStorage>;
+  write(storage: AccountStorage): Promise<void>;
+  writeMode(mode: ClaustrumMode, transition?: CustodyTransitionState): Promise<void>;
+};
+declare function withAccountStoreTransaction<T>(action: (transaction: AccountStoreTransaction) => Promise<T>, paths: AccountPaths): Promise<T>;
+/**
+ * Read-modify-write the account store atomically under the save lock.
+ *
+ * Unlike saveAccounts (which UNION-merges the incoming accounts with the latest
+ * on-disk set so concurrent ADDS from another process are never lost), this
+ * reads the freshest state under the lock and writes the mutator's result
+ * AUTHORITATIVELY — no union. That is required for structural edits (remove,
+ * reorder): a union cannot express a deletion (the removed id reappears from
+ * `latest`) or a reordering (the union is seeded latest-first). Because the
+ * mutator runs against freshly-read state under the lock, an add committed by a
+ * concurrent process is still visible to it and preserved.
+ *
+ * The mutator may edit `current` in place and return it, or return a new
+ * storage object. Returning undefined means "no change" and still rewrites the
+ * freshly-read state (a harmless idempotent write).
+ *
+ * Load-time drop preservation: if normalizeAccount (called inside
+ * normalizeStorage) rejects an account whose id IS in the raw config roster,
+ * the previous behavior would erase that id silently on the next write. This
+ * function now carries the dropped raw entry through to the written config
+ * verbatim, so the on-disk state always matches the operator's intent (an
+ * account they added, even if temporarily un-loadable, stays in their list
+ * until they deliberately remove it).
+ *
+ * Removal seam: when the caller knows they are removing an id (e.g. the CLI
+ * `remove` command) and that id may be load-dropped — in which case the
+ * mutator cannot find it in `current.accounts` to splice it — the caller can
+ * pass `options.allowDrop: [id]`. Ids in `allowDrop` are NOT preserved; the
+ * mutator's splice still no-ops on a dropped id, but the absence of
+ * preservation completes the removal end-to-end.
+ */
+interface MutateAccountsContext {
+  /** Valid string ids read from the raw config while both store locks are held. */
+  rawRosterIds: readonly string[];
+  /** Ids retained after normalization and validation, before the mutator ran. */
+  loadedRosterIds: readonly string[];
+}
+declare function mutateAccounts(mutate: (current: AccountStorage, context?: MutateAccountsContext) => AccountStorage | undefined, paths: AccountPaths, options?: {
+  allowDrop?: readonly string[];
+}): Promise<AccountStorage>;
+//#endregion
+//#region ../core/dist/oauth.d.ts
+interface IdTokenClaims {
+  chatgpt_account_id?: string;
+  email?: string;
+  organizations?: Array<{
+    id: string;
+  }>;
+  'https://api.openai.com/auth'?: {
+    chatgpt_account_id?: string;
+  };
+}
+declare function parseJwtClaims(token: string): IdTokenClaims | undefined;
+declare function extractAccountIdFromClaims(claims: IdTokenClaims): string | undefined;
+interface TokenResponse {
+  id_token: string;
+  access_token: string;
+  refresh_token: string;
+  expires_in?: number;
+}
+/**
+ * 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.
+ */
+interface IngestAccount {
+  id: string;
+  label?: string;
+  type: 'oauth';
+  access?: string;
+  refresh: string;
+  expires?: number;
+  enabled: boolean;
+  addedAt: number;
+  lastUsed: number;
+  /**
+   * When the token was obtained. Stamped at login so a freshly added account
+   * carries a refresh marker — without it, the runtime-state merge cannot tell a
+   * rotated token from a stale one (both default to 0) and a concurrent stale
+   * save could roll the token back.
+   */
+  lastRefreshedAt?: number;
+  /** Stable ChatGPT account identifier from the OAuth token claims. */
+  accountId?: string;
+}
+interface BeginAccountLoginOptions {
+  label?: string;
+  headless?: boolean;
+  signal?: AbortSignal;
+  /** Host package version, sent as the version half of the `User-Agent`. */
+  version: string;
+}
+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.
+ */
+declare function beginAccountLogin(opts: BeginAccountLoginOptions): Promise<BeginAccountLoginResult>;
+//#endregion
+//#region ../core/dist/protocol.d.ts
+type CommandModalName = 'openai-quota' | 'openai-account' | 'openai-routing' | 'openai-killswitch' | 'openai-dump' | 'openai-logging' | 'openai-cachekeep' | 'openai-reset';
+interface OpenDialogPayload {
+  command: CommandModalName;
+  text: string;
+  knobs: Record<string, unknown>;
+}
+interface RpcNotification {
+  id: number;
+  type: 'open-dialog';
+  payload: OpenDialogPayload;
+  sessionId?: string;
+}
+interface ApplyRequest {
+  command: CommandModalName;
+  arguments: string;
+  sessionId?: string;
+}
+interface ApplyResult {
+  text: string;
+  knobs: Record<string, unknown>;
+}
+//#endregion
+//#region ../core/dist/refresh-all-quota.d.ts
+interface RefreshAllQuotaResult {
+  account: string;
+  ok: boolean;
+  error?: string;
+  /**
+   * The account cannot recover on its own: the provider has rejected its
+   * credentials, so no amount of retrying will help until the operator re-adds
+   * it.
+   *
+   * Carried as a flag rather than left for the caller to infer from `error`,
+   * because sniffing an error string for a user-facing decision breaks the
+   * moment the wording changes.
+   */
+  permanent?: boolean;
+}
+//#endregion
+//#region ../core/dist/commands.d.ts
+/**
+ * The prompt-cache manager, as the commands use it.
+ *
+ * Declared structurally rather than imported: the manager itself is tied to one
+ * host's live request loader and stays there. Only the members reached through
+ * this field appear here — a status snapshot, the two lifecycle calls the
+ * cachekeep command makes, and the per-session drop the host performs when a
+ * session ends.
+ */
+interface CacheKeepManager {
+  status(): {
+    running: boolean;
+    sustain: boolean;
+    window?: {
+      startHour: number;
+      endHour: number;
+    } | undefined;
+    tracked: number;
+    generatedAt: number;
+    ttlMs: number;
+    leadMs: number;
+    maxIdleWarmMs: number;
+    maxSubagentIdleMs: number;
+    targets: ReadonlyArray<{
+      sessionKey: string;
+      accountId?: string;
+      cacheExpiresAt: number;
+      lastWarmedAt?: number;
+      backoffUntil?: number;
+    }>;
+  };
+  start(): void;
+  stop(): void;
+  remove(sessionKey: string): void;
+}
+interface CommandContext {
+  accountStoragePath: string;
+  /**
+   * Runtime-state file that goes with `accountStoragePath`. Required, and
+   * resolved by the host: nothing here derives one path from the other.
+   */
+  accountStatePath: string;
+  /** Host package version, sent as the version half of the OAuth `User-Agent`. */
+  packageVersion: string;
+  quotaManager: QuotaManager;
+  loadAccounts: typeof loadAccounts;
+  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;
+  /** Updates the live loader's main-agent idle-cap bypass gate. */
+  setCacheKeepSustain?: (enabled: boolean) => void;
+  /** Updates the live loader's clock-hour warm window. undefined = no window. */
+  setCacheKeepWindow?: (window: {
+    startHour: number;
+    endHour: number;
+  } | undefined) => void;
+  /** Clears only the sticky account assignment for one OpenCode session. */
+  clearStickyRouting?: (sessionId: string) => Promise<boolean>;
+  /** Resolves the current session's usable sticky account, if one exists. */
+  getStickyRouting?: (sessionId: string) => Promise<string | undefined>;
+  resolveResetTarget?: (accountKey: string) => Promise<ResetTargetIdentity>;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  randomUUID?: () => string;
+  /** Starts an OAuth account-add flow; injected by the runtime boundary. */
+  beginAccountLogin?: typeof beginAccountLogin;
+  refreshResetTargetQuota?: (accountKey: string) => Promise<RefreshAllQuotaResult>;
+  enterClaustrumMode?: () => Promise<{
+    status: 'completed' | 'incomplete' | 'aborted';
+    outcomes: Record<string, string>;
+    reason?: string;
+  }>;
+  leaveClaustrumMode?: () => Promise<void>;
+  withFallbackAccountLock?: <T>(accountId: string, action: () => Promise<T>) => Promise<T>;
+  checkUsableCustodyBinding?: (account: OAuthAccount) => Promise<{
+    ready: true;
+    accountId: string;
+  } | {
+    ready: false;
+    reason: string;
+  }>;
+}
+interface ResetTargetIdentity {
+  accountKey: string;
+  label: string;
+  accessToken: string;
+  chatgptAccountId?: string;
+  onAuthFailure?: (status: number) => Promise<void>;
+}
+//#endregion
+export { CustodyManifestIo as C, detectClaustrumConnection as E, acquireRefreshFileLock as S, QuotaManager as T, loadAccounts as _, CommandModalName as a, ClaustrumCredentialCache as b, IdTokenClaims as c, parseJwtClaims as d, AccountStorage as f, OAuthQuotaSnapshot as g, OAuthAccount as h, ApplyResult as i, TokenResponse as l, FallbackAccount as m, ResetTargetIdentity as n, OpenDialogPayload as o, AccountStoreTransaction as p, ApplyRequest as r, RpcNotification as s, CommandContext as t, extractAccountIdFromClaims as u, mutateAccounts as v, CustodyManifestReadResult as w, resolveFallbackAccess as x, withAccountStoreTransaction as y };