@wenathlan/devthink 2.0.12 → 2.0.14

package/dist/accounts.d.ts

@@ -0,0 +1,409 @@
+/**
+ * @fileoverview accounts.ts — the account manager core of the merged provider lineage
+ * @module auth/accounts
+ * @description
+ *  Production-ready multi-account management for the provider plugin.
+ *  MERGED FILE - superset of every previous duplicate:
+ *  - Multiple Google accounts with refresh token support
+ *  - Storage at ~/.config/opencode/antigravity-accounts.json (chmod 600, atomic write)
+ *  - Round-robin + sticky active account rotation
+ *  - Double-checked locking for access token refresh
+ *  - Quota/429 detection with automatic rotation
+ *  - Background refresh of tokens close to expiry
+ *  - Import from antigravity-manager (multiple legacy formats)
+ *  - Official Gemini CLI bypass headers
+ *  - Ported from the flat-file variant: legacy flat-file reader (Account[] format,
+ *    type Account, AccountsFileV3 wrapper), QuotaInfo reporting type,
+ *    QuotaExhaustedOptions, RefreshResult, ensureAccountsFile/loadAccountsSnapshot
+ *    helpers and resolveAccountsPath/resolveConfigDir/
+ *    resolveAntagravityManagerCandidates path resolvers.
+ *
+ *  Zero external dependencies: only node:* builtins + global fetch (Node 18+).
+ *
+ * @author ONDA 3 - Core Modules
+ * @license MIT
+ * @version 3.1.0
+ */
+import { GEMINI_CLI_OAUTH_CLIENT_ID, GEMINI_CLI_OAUTH_CLIENT_SECRET, OAUTH_TOKEN_URL, PROJECT_FALLBACK } from "./constants.js";
+import { GEMINI_CLI_USER_AGENT_MINIMAL as GEMINI_CLI_USER_AGENT, GEMINI_CLI_USER_AGENT as GEMINI_CLI_USER_AGENT_FULL } from "./constants.js";
+import { X_GOOG_API_CLIENT_GEMINI_CLI as X_GOOG_API_CLIENT } from "./fingerprint.js";
+export { GEMINI_CLI_OAUTH_CLIENT_ID, GEMINI_CLI_OAUTH_CLIENT_SECRET, OAUTH_TOKEN_URL, PROJECT_FALLBACK, GEMINI_CLI_USER_AGENT, GEMINI_CLI_USER_AGENT_FULL, X_GOOG_API_CLIENT, };
+/** Official Gemini CLI OAuth2 Client ID - raw without suffix */
+export declare const GEMINI_CLI_CLIENT_ID_RAW: "681255809395-oo8f…b135j";
+/**
+ * Antigravity CLI OAuth client (`agy` binary) — the client the provider
+ * account console presents for NEW logins since 2.1.8. v2.1.16 single-owner
+ * fix: imported from constants.js (the layer-0 raw-value owner —
+ * env-overridable through ANTIGRAVITY_CLIENT_ID /
+ * ANTIGRAVITY_CLIENT_SECRET); the former local segment-assembled copy was a
+ * byte-identical duplicate.
+ */
+export declare const ANTIGRAVITY_CLI_OAUTH_CLIENT_ID: string;
+/** Antigravity CLI client secret — alias of the constants.js owner (v2.1.16). */
+export declare const ANTIGRAVITY_CLI_OAUTH_CLIENT_SECRET: string;
+/** Bypass headers - canonical values required by WAVE 3.
+ * v2.1.16 single-owner fix: alias of constants.GEMINI_CLI_USER_AGENT (the
+ * full live-validated UA string — byte-identical to the former local copy). */
+import { MODELS_2026_LEGACY as MODELS_2026 } from "./models.js";
+import type { Model2026 } from "./models.js";
+export { MODELS_2026 };
+export type { Model2026 };
+export interface OAuthClientConfig {
+    clientId: string;
+    clientSecret: string;
+}
+export type OAuthClientKey = "gemini-cli" | "antigravity-manager" | "antigravity" | "custom" | string;
+export interface AccountMetadataV3 {
+    /** Normalized lower-case email */
+    email: string;
+    /** OAuth2 refresh token (long-lived) */
+    refreshToken: string;
+    /** Current access token (short-lived, 1h) */
+    accessToken?: string | undefined;
+    /** Epoch ms when accessToken expires */
+    expiryDate?: number | undefined;
+    /** Linked Cloud Project ID (or fallback) */
+    projectId?: string | undefined;
+    /** Whether the account is enabled for use */
+    enabled: boolean;
+    /** Identifying key of the OAuth client used */
+    oauthClientKey: OAuthClientKey;
+    /** Custom OAuth config, if oauthClientKey=custom */
+    oauthClientConfig?: OAuthClientConfig | undefined;
+    /** Epoch ms of last successful refresh */
+    lastRefresh?: number | undefined;
+    /** Epoch ms of record creation */
+    createdAt: number;
+    /** Epoch ms of last use (for LRU / rotation) */
+    lastUsedAt?: number | undefined;
+    /** Consecutive failure counter (quota, 401, etc) */
+    failureCount?: number | undefined;
+    /** Reason for temporary disablement */
+    disabledReason?: string | undefined;
+    /** Epoch ms until which the account stays disabled (cooldown) */
+    disabledUntil?: number | undefined;
+    /** Scopes this account holds (optional, for audit) */
+    scopes?: string[] | undefined;
+}
+export interface AccountStore {
+    /** Schema version - always 3 */
+    version: 3;
+    /** Account list */
+    accounts: AccountMetadataV3[];
+    /** Active email in sticky mode */
+    activeEmail?: string | null;
+    /** Round-robin rotation index */
+    rotationIndex?: number;
+    /** Selection strategy: round-robin (default) or sticky */
+    rotationStrategy?: "round-robin" | "sticky";
+    /** When the store was created */
+    createdAt?: number | undefined;
+    /** Last update */
+    updatedAt?: number | undefined;
+    /** Last error-driven rotation */
+    lastRotationAt?: number | undefined;
+    /** Email that caused the last rotation (for debug) */
+    lastRotatedFrom?: string | undefined;
+}
+export type RotationStrategy = "round-robin" | "sticky";
+export interface AddAccountInput {
+    email: string;
+    refreshToken: string;
+    accessToken?: string;
+    expiryDate?: number;
+    projectId?: string;
+    enabled?: boolean;
+    oauthClientKey?: OAuthClientKey;
+    oauthClientConfig?: OAuthClientConfig;
+    scopes?: string[];
+}
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    updated: number;
+    errors: string[];
+    sources: string[];
+    accounts: AccountMetadataV3[];
+}
+export interface TokenRefreshResponse {
+    access_token: string;
+    expires_in: number;
+    token_type: string;
+    scope?: string;
+    id_token?: string;
+}
+/**
+ * Quota snapshot per account, mirrors v1internal:retrieveUserQuotaSummary
+ * but kept lightweight in storage. Reporting-only type.
+ */
+export interface QuotaInfo {
+    /** Remaining percentage or tokens, optional */
+    remaining?: number;
+    /** Limit */
+    limit?: number;
+    /** Reset timestamp ms */
+    resetAt?: number;
+    /** True when exhausted */
+    exhausted?: boolean;
+    /** Raw group mapped from model to group, e.g. antigravity, gemini-cli */
+    group?: string;
+    /** Last check ms */
+    lastChecked?: number;
+    /** Per-model counters when dual pool */
+    pools?: Record<string, {
+        remaining?: number;
+        resetAt?: number;
+    }>;
+}
+/**
+ * V3 legacy Account - flat storage format compatible with the
+ * antigravity-manager flat export {email, refresh_token}.
+ */
+export interface Account {
+    /** Unique email, lowercased */
+    email: string;
+    /** Google OAuth refresh token (1//...) */
+    refreshToken: string;
+    /** Cached bearer access token */
+    accessToken?: string | undefined;
+    /** Expiry epoch ms (Date.now() + expires_in*1000) */
+    expiry?: number | undefined;
+    /** Cloud project id resolved via loadCodeAssist / onboardUser */
+    projectId?: string | undefined;
+    /** Soft disabled flag - user can toggle */
+    disabled?: boolean | undefined;
+    /** Quota exhausted until epoch ms - skip in rotation */
+    quotaExhaustedUntil?: number | undefined;
+    /** Last usage epoch ms */
+    lastUsed?: number | undefined;
+    /** Creation epoch ms */
+    createdAt?: number | undefined;
+    /** Update epoch ms */
+    updatedAt?: number | undefined;
+    /** Cached quota snapshot */
+    quota?: QuotaInfo | undefined;
+    /** Optional stable id (uuid) */
+    id?: string | undefined;
+    /** Account pool type */
+    type?: "antigravity" | "gemini-cli" | "auto" | string | undefined;
+    /** Display name from userinfo */
+    displayName?: string | undefined;
+    /** Optional metadata - not persisted critically */
+    metadata?: Record<string, unknown> | undefined;
+}
+/** Flat file wrapper - versioned for forward migration */
+export interface AccountsFileV3 {
+    version: 3;
+    accounts: Account[];
+    lastRotationIndex?: number;
+    lastStickyEmail?: string | null;
+    updatedAt?: number;
+    /** Optional fallback project cache */
+    fallbackProjectId?: string;
+}
+/** Result of a token refresh in flat shape */
+export interface RefreshResult {
+    accessToken: string;
+    /** Expiry epoch ms */
+    expiry: number;
+    projectId?: string;
+    raw?: Record<string, unknown>;
+}
+/** Options for marking quota exhaustion */
+export interface QuotaExhaustedOptions {
+    durationMs?: number;
+    reason?: string;
+    group?: string;
+    model?: string;
+}
+/**
+ * Resolves the config directory honoring OPENCODE_CONFIG_DIR env fallback.
+ * Pure resolver - no side effects here.
+ */
+import { resolveConfigDir } from "./config.js";
+export { resolveConfigDir };
+export declare function resolveAccountsFilePath(customDir?: string): string;
+/**
+ * Resolves the full accounts file path.
+ * When custom is provided it is treated as a complete file path override;
+ * otherwise resolves to <configDir>/antigravity-accounts.json.
+ */
+export declare function resolveAccountsPath(custom?: string): string;
+/**
+ * Candidate paths for antigravity-manager import.
+ * Honors ANTIGRAVITY_MANAGER_ACCOUNTS_PATH env override and Windows AppData.
+ */
+export declare function resolveAntagravityManagerCandidates(): string[];
+/**
+ * Helper to ensure the accounts file exists with safe perms, idempotent.
+ * Creates an empty AccountsFileV3 payload when missing.
+ *
+ * @param filePath optional full file path override
+ * @returns resolved file path
+ */
+export declare function ensureAccountsFile(filePath?: string): Promise<string>;
+/**
+ * Quick utility - reads accounts without a manager instance.
+ * Uses the legacy flat-file reader, tolerant to every historical shape.
+ *
+ * @param filePath optional full file path override
+ * @returns sanitized Account[] snapshot (empty on missing/corrupt file)
+ */
+export declare function loadAccountsSnapshot(filePath?: string): Promise<Account[]>;
+export declare function isQuotaError(err: unknown): boolean;
+export interface AccountManagerOptions {
+    /** Override of the base directory (default ~/.config/opencode) */
+    configDir?: string;
+    /** File name (default antigravity-accounts.json) */
+    fileName?: string;
+    /** Default strategy if store does not have one */
+    rotationStrategy?: RotationStrategy;
+    /** Custom full path (takes precedence over configDir+fileName) */
+    filePath?: string;
+    /** Optional logger */
+    logger?: {
+        info?: (msg: string, ...args: any[]) => void;
+        warn?: (msg: string, ...args: any[]) => void;
+        error?: (msg: string, ...args: any[]) => void;
+        debug?: (msg: string, ...args: any[]) => void;
+    };
+    /** Disables background auto-refresh timer */
+    disableBackgroundTimer?: boolean;
+}
+export declare class AccountManager {
+    private readonly storePath;
+    private store;
+    private rotationIdx;
+    private readonly refreshLocks;
+    private backgroundTimer?;
+    private readonly logger;
+    private readonly options;
+    constructor(opts?: AccountManagerOptions);
+    /**
+     * Loads accounts from ~/.config/opencode/antigravity-accounts.json
+     * - Creates the file if missing with default store
+     * - chmod 600 on every read/write
+     * - Sanitizes schema V3
+     */
+    loadAccounts(): AccountStore;
+    /**
+     * Saves store to disk atomically with chmod 600
+     */
+    saveAccounts(): void;
+    /**
+     * Saves a custom store atomically - used for tests / import
+     */
+    saveAccountsAtomic(store: AccountStore): void;
+    getAccountCount(): number;
+    getEnabledAccounts(): AccountMetadataV3[];
+    listAccounts(): AccountMetadataV3[];
+    /** List with refreshToken masked (safe for log/UI) */
+    listAccountsMasked(): Array<Omit<AccountMetadataV3, "refreshToken"> & {
+        refreshTokenMasked: string;
+    }>;
+    findAccount(email: string): AccountMetadataV3 | undefined;
+    private findAccountIndex;
+    /**
+     * Adds a new account. If email already exists, updates refreshToken and other data.
+     * Returns the added/updated account.
+     */
+    addAccount(input: AddAccountInput): AccountMetadataV3;
+    /**
+     * Removes account by email. Returns true if removed.
+     */
+    removeAccount(email: string): boolean;
+    getActiveAccount(): AccountMetadataV3 | null;
+    /** Sets the active account (sticky-mode override). Optionally sets strategy to sticky. */
+    setActive(email: string, opts?: {
+        sticky?: boolean;
+    }): AccountMetadataV3;
+    enableAccount(email: string): AccountMetadataV3;
+    disableAccount(email: string, reason?: string, cooldownMs?: number): AccountMetadataV3;
+    enable(email: string): AccountMetadataV3;
+    disable(email: string, reason?: string, cooldownMs?: number): AccountMetadataV3;
+    /**
+     * Detects quota/429 errors and rotates to the next enabled account.
+     * Accepts flexible signatures:
+     * - rotateOnError(error)
+     * - rotateOnError(email, error)
+     * - rotateOnError(error, email)
+     */
+    rotateOnError(errorOrEmail: unknown, maybeErrorOrEmail?: unknown): AccountMetadataV3 | null;
+    /**
+     * Refresh with double-checked locking
+     * - Checks expiry before lock
+     * - If a lock exists, waits for it and re-checks
+     * - Only then performs the refresh
+     */
+    refreshAccessTokenIfNeeded(email: string, force?: boolean): Promise<AccountMetadataV3>;
+    /**
+     * Returns a valid access token, refreshing if needed.
+     * If email is omitted, uses the active account (round-robin/sticky).
+     */
+    getValidAccessToken(email?: string): Promise<string>;
+    /**
+     * Background refresh of all enabled accounts close to expiry
+     * - Does not block callers
+     * - Uses allSettled so the batch never fails as a whole
+     */
+    backgroundRefresh(): Promise<void>;
+    /**
+     * Starts background refresh without awaiting (fire-and-forget)
+     */
+    triggerBackgroundRefresh(): void;
+    private static getAntigravityManagerCandidatePaths;
+    private static extractAccountsFromRaw;
+    /**
+     * Imports accounts from existing antigravity-manager installations.
+     * Tries multiple paths and legacy formats (including the flat Account[]
+     * reader), merging into the current store without duplicates.
+     */
+    importFromAntigravityManager(): Promise<ImportResult>;
+    /** Alias compat requested by consumers */
+    importFromAntigravity(): Promise<ImportResult>;
+    /** Additional alias for backwards compatibility */
+    importAccounts(): Promise<ImportResult>;
+    /** Clears the background timer (useful in tests) */
+    destroy(): void;
+    /** File path */
+    getStorePath(): string;
+    /** Raw store (clone) */
+    getStore(): AccountStore;
+    /** Sets the rotation strategy */
+    setRotationStrategy(strategy: RotationStrategy): void;
+}
+/** Returns the default lazy singleton instance */
+export declare function getDefaultAccountManager(opts?: AccountManagerOptions): AccountManager;
+/** Resets the singleton (tests) */
+export declare function resetDefaultAccountManager(): void;
+/** Quick helper to obtain a valid token using the singleton */
+export declare function getValidAccessToken(email?: string, opts?: AccountManagerOptions): Promise<string>;
+/** Quick helper to obtain the active account */
+export declare function getActiveAccount(opts?: AccountManagerOptions): AccountMetadataV3 | null;
+export default AccountManager;
+export declare const ACCOUNTS_FILE_PATH: string;
+export declare const ACCOUNTS_INFO: {
+    readonly CLIENT_ID_RAW: "681255809395-oo8f…b135j";
+    readonly CLIENT_ID: string;
+    readonly CLIENT_SECRET: string;
+    readonly SCOPES: readonly ["https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/userinfo.email", "https://www.googleapis.com/auth/userinfo.profile"];
+    readonly TOKEN_URL: "https://oauth2.googleapis.com/token";
+    readonly USER_AGENT: "GeminiCLI/0.57.0";
+    readonly USER_AGENT_FULL: "GeminiCLI/0.57.0/gemini-3-pro-preview (linux; x64; GitHub) google-api-nodejs-client/9.15.1";
+    readonly X_GOOG_API_CLIENT: "gl-node/22.19.0";
+    readonly CLIENT_METADATA: "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI";
+    readonly CLOUDCODE_BASE_URL: "https://cloudcode-pa.googleapis.com";
+    readonly CLOUDCODE_ENDPOINTS: {
+        readonly base: "https://cloudcode-pa.googleapis.com";
+        readonly loadCodeAssist: "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist";
+        readonly onboardUser: "https://cloudcode-pa.googleapis.com/v1internal:onboardUser";
+        readonly fetchAvailableModels: "https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels";
+        readonly generateContent: "https://cloudcode-pa.googleapis.com/v1internal:generateContent";
+        readonly streamGenerateContent: "https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent";
+        readonly retrieveUserQuotaSummary: "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuotaSummary";
+    };
+    readonly PROJECT_FALLBACK: "rising-fact-p41fc";
+    readonly MODELS_2026: readonly ["antigravity-gemini-3-pro", "antigravity-gemini-3.1-pro", "antigravity-gemini-3-flash", "antigravity-claude-sonnet-4-6", "antigravity-claude-opus-4-6-thinking", "gemini-2.5-flash", "gemini-2.5-pro", "gemini-3-flash-preview", "gemini-3-pro-preview", "gemini-3.1-pro-preview", "gemini-3.1-pro-preview-customtools"];
+    readonly ACCOUNTS_FILE_PATH: string;
+};
+//# sourceMappingURL=accounts.d.ts.map