gsd-pi 2.10.2 → 2.10.5

package/node_modules/@gsd/pi-coding-agent/dist/core/auth-storage.d.ts

@@ -2,6 +2,9 @@
  * Credential storage for API keys and OAuth tokens.
  * Handles loading, saving, and refreshing credentials from auth.json.
  *
+ * Supports multiple credentials per provider with round-robin selection,
+ * session-sticky hashing, and automatic rate-limit fallback.
+ *
  * Uses file locking to prevent race conditions when multiple pi instances
  * try to refresh tokens simultaneously.
  */
@@ -14,7 +17,11 @@ export type OAuthCredential = {
     type: "oauth";
 } & OAuthCredentials;
 export type AuthCredential = ApiKeyCredential | OAuthCredential;
-export type AuthStorageData = Record<string, AuthCredential>;
+/**
+ * On-disk format: each provider maps to a single credential or an array of credentials.
+ * Single credentials are normalized to arrays at load time for internal use.
+ */
+export type AuthStorageData = Record<string, AuthCredential | AuthCredential[]>;
 type LockResult<T> = {
     result: T;
     next?: string;
@@ -37,8 +44,10 @@ export declare class InMemoryAuthStorageBackend implements AuthStorageBackend {
     withLock<T>(fn: (current: string | undefined) => LockResult<T>): T;
     withLockAsync<T>(fn: (current: string | undefined) => Promise<LockResult<T>>): Promise<T>;
 }
+export type UsageLimitErrorType = "rate_limit" | "quota_exhausted" | "server_error" | "unknown";
 /**
  * Credential storage backed by a JSON file.
+ * Supports multiple credentials per provider with round-robin rotation and rate-limit fallback.
  */
 export declare class AuthStorage {
     private storage;
@@ -47,6 +56,16 @@ export declare class AuthStorage {
     private fallbackResolver?;
     private loadError;
     private errors;
+    /**
+     * Round-robin index per provider. Incremented on each call to getApiKey
+     * when no sessionId is provided.
+     */
+    private providerRoundRobinIndex;
+    /**
+     * Backoff tracking per provider per credential index.
+     * Map<provider, Map<credentialIndex, backoffExpiresAt>>
+     */
+    private credentialBackoff;
     private constructor();
     static create(authPath?: string): AuthStorage;
     static fromStorage(storage: AuthStorageBackend): AuthStorage;
@@ -67,21 +86,28 @@ export declare class AuthStorage {
     setFallbackResolver(resolver: (provider: string) => string | undefined): void;
     private recordError;
     private parseStorageData;
+    /**
+     * Normalize a storage entry to an array of credentials.
+     * Handles both single credential (backward compat) and array formats.
+     */
+    getCredentialsForProvider(provider: string): AuthCredential[];
     /**
      * Reload credentials from storage.
      */
     reload(): void;
     private persistProviderChange;
     /**
-     * Get credential for a provider.
+     * Get the first credential for a provider (backward-compatible).
      */
     get(provider: string): AuthCredential | undefined;
     /**
-     * Set credential for a provider.
+     * Set credential for a provider. For API key credentials, appends to
+     * existing credentials (accumulation on duplicate login). For OAuth,
+     * replaces (only one OAuth token per provider makes sense).
      */
     set(provider: string, credential: AuthCredential): void;
     /**
-     * Remove credential for a provider.
+     * Remove all credentials for a provider.
      */
     remove(provider: string): void;
     /**
@@ -99,8 +125,14 @@ export declare class AuthStorage {
     hasAuth(provider: string): boolean;
     /**
      * Get all credentials (for passing to getOAuthApiKey).
-     */
-    getAll(): AuthStorageData;
+     * Returns normalized format where each provider has a single credential
+     * (the first one) for backward compatibility with OAuth refresh.
+     *
+     * NOTE: For providers with multiple API keys, only the first credential is
+     * returned. This is intentional — callers use this for OAuth refresh only,
+     * which is always single-credential. Do not use for API key enumeration.
+     */
+    getAll(): Record<string, AuthCredential>;
     drainErrors(): Error[];
     /**
      * Login to an OAuth provider.
@@ -110,21 +142,49 @@ export declare class AuthStorage {
      * Logout from a provider.
      */
     logout(provider: string): void;
+    /**
+     * Check if a credential index is currently backed off.
+     */
+    private isCredentialBackedOff;
+    /**
+     * Select the best credential index for a provider.
+     * - If sessionId is provided, uses session-sticky hashing as the starting point.
+     * - Otherwise, uses round-robin as the starting point.
+     * - Skips credentials that are currently backed off.
+     * - Returns -1 if all credentials are backed off.
+     */
+    private selectCredentialIndex;
+    /**
+     * Mark a credential as rate-limited. Finds the credential that was most
+     * recently used for this provider+session and backs it off.
+     *
+     * @returns true if another credential is available (caller should retry),
+     *          false if all credentials for this provider are backed off.
+     */
+    markUsageLimitReached(provider: string, sessionId?: string, options?: {
+        errorType?: UsageLimitErrorType;
+    }): boolean;
     /**
      * Refresh OAuth token with backend locking to prevent race conditions.
      * Multiple pi instances may try to refresh simultaneously when tokens expire.
      */
     private refreshOAuthTokenWithLock;
+    /**
+     * Resolve an API key from a single credential.
+     */
+    private resolveCredentialApiKey;
     /**
      * Get API key for a provider.
      * Priority:
      * 1. Runtime override (CLI --api-key)
-     * 2. API key from auth.json
-     * 3. OAuth token from auth.json (auto-refreshed with locking)
-     * 4. Environment variable
-     * 5. Fallback resolver (models.json custom providers)
-     */
-    getApiKey(providerId: string): Promise<string | undefined>;
+     * 2. Credential(s) from auth.json (with round-robin / session-sticky selection)
+     * 3. Environment variable
+     * 4. Fallback resolver (models.json custom providers)
+     *
+     * @param providerId - The provider to get an API key for
+     * @param sessionId - Optional session ID for sticky credential selection
+     */
+    getApiKey(providerId: string, sessionId?: string): Promise<string | undefined>;
     /**
      * Get all registered OAuth providers
      */

package/node_modules/@gsd/pi-coding-agent/dist/core/auth-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-storage.d.ts","sourceRoot":"","sources":["../../src/core/auth-storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-storage.d.ts","sourceRoot":"","sources":["../../src/core/auth-storage.ts"],"names":[],"mappings":"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"}

package/node_modules/@gsd/pi-coding-agent/dist/core/auth-storage.js

@@ -2,6 +2,9 @@
  * Credential storage for API keys and OAuth tokens.
  * Handles loading, saving, and refreshing credentials from auth.json.
  *
+ * Supports multiple credentials per provider with round-robin selection,
+ * session-sticky hashing, and automatic rate-limit fallback.
+ *
  * Uses file locking to prevent race conditions when multiple pi instances
  * try to refresh tokens simultaneously.
  */
@@ -137,8 +140,43 @@ export class InMemoryAuthStorageBackend {
         return result;
     }
 }
+// ============================================================================
+// Backoff durations for different error types (milliseconds)
+// ============================================================================
+const BACKOFF_RATE_LIMIT_MS = 30_000; // 30s for rate limit / 429
+const BACKOFF_QUOTA_EXHAUSTED_MS = 30 * 60_000; // 30min for quota exhausted
+const BACKOFF_SERVER_ERROR_MS = 20_000; // 20s for 5xx server errors
+const BACKOFF_DEFAULT_MS = 60_000; // 60s fallback
+/**
+ * Get backoff duration for an error type.
+ */
+function getBackoffDuration(errorType) {
+    switch (errorType) {
+        case "rate_limit":
+            return BACKOFF_RATE_LIMIT_MS;
+        case "quota_exhausted":
+            return BACKOFF_QUOTA_EXHAUSTED_MS;
+        case "server_error":
+            return BACKOFF_SERVER_ERROR_MS;
+        default:
+            return BACKOFF_DEFAULT_MS;
+    }
+}
+/**
+ * Simple string hash for session-sticky credential selection.
+ * Returns a positive integer.
+ */
+function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash + char) | 0;
+    }
+    return Math.abs(hash);
+}
 /**
  * Credential storage backed by a JSON file.
+ * Supports multiple credentials per provider with round-robin rotation and rate-limit fallback.
  */
 export class AuthStorage {
     constructor(storage) {
@@ -147,6 +185,16 @@ export class AuthStorage {
         this.runtimeOverrides = new Map();
         this.loadError = null;
         this.errors = [];
+        /**
+         * Round-robin index per provider. Incremented on each call to getApiKey
+         * when no sessionId is provided.
+         */
+        this.providerRoundRobinIndex = new Map();
+        /**
+         * Backoff tracking per provider per credential index.
+         * Map<provider, Map<credentialIndex, backoffExpiresAt>>
+         */
+        this.credentialBackoff = new Map();
         this.reload();
     }
     static create(authPath) {
@@ -190,6 +238,18 @@ export class AuthStorage {
         }
         return JSON.parse(content);
     }
+    /**
+     * Normalize a storage entry to an array of credentials.
+     * Handles both single credential (backward compat) and array formats.
+     */
+    getCredentialsForProvider(provider) {
+        const entry = this.data[provider];
+        if (!entry)
+            return [];
+        if (Array.isArray(entry))
+            return entry;
+        return [entry];
+    }
     /**
      * Reload credentials from storage.
      */
@@ -230,23 +290,50 @@ export class AuthStorage {
         }
     }
     /**
-     * Get credential for a provider.
+     * Get the first credential for a provider (backward-compatible).
      */
     get(provider) {
-        return this.data[provider] ?? undefined;
+        const creds = this.getCredentialsForProvider(provider);
+        return creds[0] ?? undefined;
     }
     /**
-     * Set credential for a provider.
+     * Set credential for a provider. For API key credentials, appends to
+     * existing credentials (accumulation on duplicate login). For OAuth,
+     * replaces (only one OAuth token per provider makes sense).
      */
     set(provider, credential) {
-        this.data[provider] = credential;
-        this.persistProviderChange(provider, credential);
+        if (credential.type === "api_key") {
+            const existing = this.getCredentialsForProvider(provider);
+            // Deduplicate: don't add if same key already exists
+            const isDuplicate = existing.some((c) => c.type === "api_key" && c.key === credential.key);
+            if (isDuplicate)
+                return;
+            const updated = [...existing, credential];
+            this.data[provider] = updated.length === 1 ? updated[0] : updated;
+            this.persistProviderChange(provider, updated.length === 1 ? updated[0] : updated);
+        }
+        else {
+            // OAuth: replace any existing OAuth credential, keep API keys
+            const existing = this.getCredentialsForProvider(provider);
+            const apiKeys = existing.filter((c) => c.type === "api_key");
+            if (apiKeys.length === 0) {
+                this.data[provider] = credential;
+                this.persistProviderChange(provider, credential);
+            }
+            else {
+                const updated = [...apiKeys, credential];
+                this.data[provider] = updated;
+                this.persistProviderChange(provider, updated);
+            }
+        }
     }
     /**
-     * Remove credential for a provider.
+     * Remove all credentials for a provider.
      */
     remove(provider) {
         delete this.data[provider];
+        this.providerRoundRobinIndex.delete(provider);
+        this.credentialBackoff.delete(provider);
         this.persistProviderChange(provider, undefined);
     }
     /**
@@ -278,9 +365,19 @@ export class AuthStorage {
     }
     /**
      * Get all credentials (for passing to getOAuthApiKey).
+     * Returns normalized format where each provider has a single credential
+     * (the first one) for backward compatibility with OAuth refresh.
+     *
+     * NOTE: For providers with multiple API keys, only the first credential is
+     * returned. This is intentional — callers use this for OAuth refresh only,
+     * which is always single-credential. Do not use for API key enumeration.
      */
     getAll() {
-        return { ...this.data };
+        const result = {};
+        for (const [provider, entry] of Object.entries(this.data)) {
+            result[provider] = Array.isArray(entry) ? entry[0] : entry;
+        }
+        return result;
     }
     drainErrors() {
         const drained = [...this.errors];
@@ -304,6 +401,101 @@ export class AuthStorage {
     logout(provider) {
         this.remove(provider);
     }
+    /**
+     * Check if a credential index is currently backed off.
+     */
+    isCredentialBackedOff(provider, index) {
+        const providerBackoff = this.credentialBackoff.get(provider);
+        if (!providerBackoff)
+            return false;
+        const expiresAt = providerBackoff.get(index);
+        if (expiresAt === undefined)
+            return false;
+        if (Date.now() >= expiresAt) {
+            providerBackoff.delete(index);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Select the best credential index for a provider.
+     * - If sessionId is provided, uses session-sticky hashing as the starting point.
+     * - Otherwise, uses round-robin as the starting point.
+     * - Skips credentials that are currently backed off.
+     * - Returns -1 if all credentials are backed off.
+     */
+    selectCredentialIndex(provider, credentials, sessionId) {
+        if (credentials.length === 0)
+            return -1;
+        if (credentials.length === 1) {
+            return this.isCredentialBackedOff(provider, 0) ? -1 : 0;
+        }
+        let startIndex;
+        if (sessionId) {
+            startIndex = hashString(sessionId) % credentials.length;
+        }
+        else {
+            const current = this.providerRoundRobinIndex.get(provider) ?? 0;
+            startIndex = current % credentials.length;
+            this.providerRoundRobinIndex.set(provider, current + 1);
+        }
+        // Try starting from the preferred index, wrapping around
+        for (let offset = 0; offset < credentials.length; offset++) {
+            const index = (startIndex + offset) % credentials.length;
+            if (!this.isCredentialBackedOff(provider, index)) {
+                return index;
+            }
+        }
+        // All credentials are backed off
+        return -1;
+    }
+    /**
+     * Mark a credential as rate-limited. Finds the credential that was most
+     * recently used for this provider+session and backs it off.
+     *
+     * @returns true if another credential is available (caller should retry),
+     *          false if all credentials for this provider are backed off.
+     */
+    markUsageLimitReached(provider, sessionId, options) {
+        const credentials = this.getCredentialsForProvider(provider);
+        if (credentials.length === 0)
+            return false;
+        const errorType = options?.errorType ?? "rate_limit";
+        const backoffMs = getBackoffDuration(errorType);
+        // Determine which credential was just used (same logic as selectCredentialIndex
+        // but without incrementing round-robin)
+        let usedIndex;
+        if (credentials.length === 1) {
+            usedIndex = 0;
+        }
+        else if (sessionId) {
+            usedIndex = hashString(sessionId) % credentials.length;
+        }
+        else {
+            // Round-robin was already incremented in getApiKey, so the last-used
+            // index is (current - 1). Note: in a concurrent scenario where another
+            // getApiKey call fires between the original request and this backoff call,
+            // we may back off the wrong credential index. This is acceptable because:
+            // (a) pi runs single-threaded event loop, (b) backing off the wrong key
+            // is safe — it self-heals when the backoff expires.
+            const current = this.providerRoundRobinIndex.get(provider) ?? 0;
+            usedIndex = ((current - 1) % credentials.length + credentials.length) % credentials.length;
+        }
+        // Set backoff for this credential
+        let providerBackoff = this.credentialBackoff.get(provider);
+        if (!providerBackoff) {
+            providerBackoff = new Map();
+            this.credentialBackoff.set(provider, providerBackoff);
+        }
+        providerBackoff.set(usedIndex, Date.now() + backoffMs);
+        // Check if any credential is still available
+        for (let i = 0; i < credentials.length; i++) {
+            if (!this.isCredentialBackedOff(provider, i)) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Refresh OAuth token with backend locking to prevent race conditions.
      * Multiple pi instances may try to refresh simultaneously when tokens expire.
@@ -317,8 +509,10 @@ export class AuthStorage {
             const currentData = this.parseStorageData(current);
             this.data = currentData;
             this.loadError = null;
-            const cred = currentData[providerId];
-            if (cred?.type !== "oauth") {
+            // Find the OAuth credential for this provider
+            const creds = this.getCredentialsForProvider(providerId);
+            const cred = creds.find((c) => c.type === "oauth");
+            if (!cred || cred.type !== "oauth") {
                 return { result: null };
             }
             if (Date.now() < cred.expires) {
@@ -326,17 +520,28 @@ export class AuthStorage {
             }
             const oauthCreds = {};
             for (const [key, value] of Object.entries(currentData)) {
-                if (value.type === "oauth") {
-                    oauthCreds[key] = value;
+                const first = Array.isArray(value) ? value.find((c) => c.type === "oauth") : value;
+                if (first?.type === "oauth") {
+                    oauthCreds[key] = first;
                 }
             }
             const refreshed = await getOAuthApiKey(providerId, oauthCreds);
             if (!refreshed) {
                 return { result: null };
             }
+            // Update the OAuth credential in-place within the array
+            const existingEntry = currentData[providerId];
+            const newOAuthCred = { type: "oauth", ...refreshed.newCredentials };
+            let updatedEntry;
+            if (Array.isArray(existingEntry)) {
+                updatedEntry = existingEntry.map((c) => (c.type === "oauth" ? newOAuthCred : c));
+            }
+            else {
+                updatedEntry = newOAuthCred;
+            }
             const merged = {
                 ...currentData,
-                [providerId]: { type: "oauth", ...refreshed.newCredentials },
+                [providerId]: updatedEntry,
             };
             this.data = merged;
             this.loadError = null;
@@ -345,59 +550,65 @@ export class AuthStorage {
         return result;
     }
     /**
-     * Get API key for a provider.
-     * Priority:
-     * 1. Runtime override (CLI --api-key)
-     * 2. API key from auth.json
-     * 3. OAuth token from auth.json (auto-refreshed with locking)
-     * 4. Environment variable
-     * 5. Fallback resolver (models.json custom providers)
+     * Resolve an API key from a single credential.
      */
-    async getApiKey(providerId) {
-        // Runtime override takes highest priority
-        const runtimeKey = this.runtimeOverrides.get(providerId);
-        if (runtimeKey) {
-            return runtimeKey;
-        }
-        const cred = this.data[providerId];
-        if (cred?.type === "api_key") {
+    async resolveCredentialApiKey(providerId, cred) {
+        if (cred.type === "api_key") {
             return resolveConfigValue(cred.key);
         }
-        if (cred?.type === "oauth") {
+        if (cred.type === "oauth") {
             const provider = getOAuthProvider(providerId);
-            if (!provider) {
-                // Unknown OAuth provider, can't get API key
+            if (!provider)
                 return undefined;
-            }
-            // Check if token needs refresh
             const needsRefresh = Date.now() >= cred.expires;
             if (needsRefresh) {
-                // Use locked refresh to prevent race conditions
                 try {
                     const result = await this.refreshOAuthTokenWithLock(providerId);
-                    if (result) {
+                    if (result)
                         return result.apiKey;
-                    }
                 }
                 catch (error) {
                     this.recordError(error);
-                    // Refresh failed - re-read file to check if another instance succeeded
                     this.reload();
-                    const updatedCred = this.data[providerId];
-                    if (updatedCred?.type === "oauth" && Date.now() < updatedCred.expires) {
-                        // Another instance refreshed successfully, use those credentials
-                        return provider.getApiKey(updatedCred);
+                    const updatedCreds = this.getCredentialsForProvider(providerId);
+                    const updatedOAuth = updatedCreds.find((c) => c.type === "oauth");
+                    if (updatedOAuth?.type === "oauth" && Date.now() < updatedOAuth.expires) {
+                        return provider.getApiKey(updatedOAuth);
                     }
-                    // Refresh truly failed - return undefined so model discovery skips this provider
-                    // User can /login to re-authenticate (credentials preserved for retry)
                     return undefined;
                 }
             }
             else {
-                // Token not expired, use current access token
                 return provider.getApiKey(cred);
             }
         }
+        return undefined;
+    }
+    /**
+     * Get API key for a provider.
+     * Priority:
+     * 1. Runtime override (CLI --api-key)
+     * 2. Credential(s) from auth.json (with round-robin / session-sticky selection)
+     * 3. Environment variable
+     * 4. Fallback resolver (models.json custom providers)
+     *
+     * @param providerId - The provider to get an API key for
+     * @param sessionId - Optional session ID for sticky credential selection
+     */
+    async getApiKey(providerId, sessionId) {
+        // Runtime override takes highest priority
+        const runtimeKey = this.runtimeOverrides.get(providerId);
+        if (runtimeKey) {
+            return runtimeKey;
+        }
+        const credentials = this.getCredentialsForProvider(providerId);
+        if (credentials.length > 0) {
+            const index = this.selectCredentialIndex(providerId, credentials, sessionId);
+            if (index >= 0) {
+                return this.resolveCredentialApiKey(providerId, credentials[index]);
+            }
+            // All credentials backed off - fall through to env/fallback
+        }
         // Fall back to environment variable
         const envKey = getEnvApiKey(providerId);
         if (envKey)