@splashcodex/api-key-manager 5.0.2 → 5.3.0

package/bin/cli.js

@@ -1,50 +1,180 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 const args = process.argv.slice(2);
 const command = args[0];
 
+const ENV_DIR = path.join(os.homedir(), 'codedex', 'env');
+
 function printDocs() {
-    console.log(`\x1b[92m🌟 @splashcodex/api-key-manager v5.0\x1b[0m`);
-    console.log(`\x1b[96m📚 Documentation: https://www.npmjs.com/package/@splashcodex/ApiKeyManager\x1b[0m\n`);
-    console.log(`\x1b[93m🚀 Commands:\x1b[0m`);
-    console.log(`   npx @splashcodex/api-key-manager init   \x1b[90m# Scaffold a demo project in the current directory\x1b[0m`);
-    console.log(`\n\x1b[95m💡 Tip: Need help? Run init to see it in action!\x1b[0m\n`);
+    console.log(`\x1b[92m@splashcodex/api-key-manager v5.1\x1b[0m`);
+    console.log(`\x1b[96mDocs: https://www.npmjs.com/package/@splashcodex/ApiKeyManager\x1b[0m\n`);
+    console.log(`\x1b[93mCommands:\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager init    \x1b[90m# Scaffold demo + central env directory\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager setup   \x1b[90m# Create ~/codedex/env/ with template files\x1b[0m`);
+    console.log(`   npx @splashcodex/api-key-manager status  \x1b[90m# Show which env files are loaded\x1b[0m`);
+    console.log('');
+}
+
+function setupEnvDir() {
+    console.log(`\n\x1b[96mSetting up centralized env directory...\x1b[0m\n`);
+
+    if (!fs.existsSync(ENV_DIR)) {
+        fs.mkdirSync(ENV_DIR, { recursive: true });
+        console.log(`\x1b[92m[+] Created ${ENV_DIR}\x1b[0m`);
+    } else {
+        console.log(`\x1b[90m[-] ${ENV_DIR} already exists\x1b[0m`);
+    }
+
+    const templates = {
+        'common.env': [
+            '# Common environment variables shared across all projects',
+            '# DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"',
+            '# REDIS_URL="redis://localhost:6379"',
+            '# SUPABASE_URL="https://your-project.supabase.co"',
+            '# SUPABASE_ANON_KEY="your-anon-key"',
+            '',
+        ].join('\n'),
+        'llm.env': [
+            '# LLM API keys — supports comma-separated or JSON arrays',
+            '# GOOGLE_GEMINI_API_KEY="key1,key2,key3"',
+            '# OPENAI_API_KEY="sk-..."',
+            '# ANTHROPIC_API_KEY="sk-ant-..."',
+            '',
+        ].join('\n'),
+        'stripe.env': [
+            '# Stripe payment keys',
+            '# STRIPE_SECRET_KEY="sk_test_..."',
+            '# STRIPE_WEBHOOK_SECRET="whsec_..."',
+            '',
+        ].join('\n'),
+    };
+
+    for (const [name, content] of Object.entries(templates)) {
+        const filePath = path.join(ENV_DIR, name);
+        if (!fs.existsSync(filePath)) {
+            fs.writeFileSync(filePath, content);
+            console.log(`\x1b[92m[+] Created ${name}\x1b[0m`);
+        } else {
+            console.log(`\x1b[90m[-] ${name} already exists\x1b[0m`);
+        }
+    }
+
+    console.log(`\n\x1b[93mNext steps:\x1b[0m`);
+    console.log(`  1. Add your real keys to the files in ${ENV_DIR}`);
+    console.log(`  2. Back up the folder to Google Drive for portability`);
+    console.log(`  3. In your projects, add at the entry point:`);
+    console.log(`\x1b[36m     import { loadCentralEnv } from '@splashcodex/api-key-manager/env';\x1b[0m`);
+    console.log(`\x1b[36m     loadCentralEnv();\x1b[0m\n`);
+}
+
+function showStatus() {
+    console.log(`\n\x1b[96mCentralized env status\x1b[0m\n`);
+    console.log(`  Directory: ${ENV_DIR}`);
+
+    if (!fs.existsSync(ENV_DIR)) {
+        console.log(`  \x1b[31mNot found.\x1b[0m Run: npx @splashcodex/api-key-manager setup\n`);
+        return;
+    }
+
+    const files = fs.readdirSync(ENV_DIR).filter(f => f.endsWith('.env')).sort();
+    if (files.length === 0) {
+        console.log(`  \x1b[33mNo .env files found.\x1b[0m\n`);
+        return;
+    }
+
+    let totalVars = 0;
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(ENV_DIR, file), 'utf-8');
+        const vars = content.split('\n')
+            .filter(l => l.trim() && !l.trim().startsWith('#'))
+            .filter(l => l.includes('='));
+        totalVars += vars.length;
+
+        const icon = vars.length > 0 ? '\x1b[92m' : '\x1b[90m';
+        console.log(`  ${icon}${file}\x1b[0m — ${vars.length} variable(s)`);
+        for (const v of vars) {
+            const key = v.split('=')[0].trim();
+            console.log(`    \x1b[90m${key}\x1b[0m`);
+        }
+    }
+
+    console.log(`\n  Total: ${files.length} file(s), ${totalVars} variable(s)\n`);
 }
 
 function initProject() {
     const cwd = process.cwd();
-    const envPath = path.join(cwd, '.env');
     const demoPath = path.join(cwd, 'demo.ts');
 
-    console.log(`\n\x1b[96m🚀 Initializing @splashcodex/api-key-manager environment...\x1b[0m\n`);
+    console.log(`\n\x1b[96mInitializing @splashcodex/api-key-manager...\x1b[0m\n`);
 
-    // Create .env
-    if (!fs.existsSync(envPath)) {
-        fs.writeFileSync(envPath, `GOOGLE_GEMINI_API_KEY="your_api_key_1,your_api_key_2"\nOPENAI_API_KEY="sk-..."\n`);
-        console.log(`\x1b[92m[✔] Created .env file\x1b[0m`);
-    } else {
-        console.log(`\x1b[90m[-] .env already exists. Remember to add GOOGLE_GEMINI_API_KEY!\x1b[0m`);
-    }
+    // Ensure central env directory exists
+    setupEnvDir();
 
     // Create demo.ts
     if (!fs.existsSync(demoPath)) {
-        const tsCode = `import 'dotenv/config';\nimport { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';\n\nasync function main() {\n    console.log("Initialize GeminiManager...");\n    // Automatically parse GOOGLE_GEMINI_API_KEY from env\n    const result = GeminiManager.getInstance();\n    if (!result.success) {\n        console.error("Failed to initialize:", result.error);\n        return;\n    }\n    \n    const gemini = result.data;\n    \n    console.log("Executing resilient request...");\n    // Automatically handles key rotation and 429 quota limits\n    try {\n        const response = await gemini.execute(async (key) => {\n            console.log(\`[Network] Sending request with key: \${key.substring(0, 8)}...\`);\n            // Replace with actual fetch: await fetch(..., { headers: { 'x-goog-api-key': key } })\n            return "Success: Simulated API Response!";\n        });\n        console.log("Result:", response);\n    } catch (e) {\n        console.error("All keys exhausted or network failed.", e.message);\n    }\n}\n\nmain();\n`;
+        const tsCode = `/**
+ * Demo: @splashcodex/api-key-manager v5.1
+ *
+ * Shows the two-layer pattern:
+ *   Layer 1: loadCentralEnv() loads keys from ~/codedex/env/
+ *   Layer 2: GeminiManager handles rotation, retries, circuit breaking
+ */
+import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+import { GeminiManager } from '@splashcodex/api-key-manager/presets/gemini';
+
+// Layer 1: Load centralized environment
+const envResult = loadCentralEnv();
+console.log(\`Loaded \${envResult.varsSet} env vars from \${envResult.filesLoaded.length} files\`);
+
+async function main() {
+    // Layer 2: Initialize key manager (reads from process.env)
+    const result = GeminiManager.getInstance();
+    if (!result.success) {
+        console.error("Failed:", result.error.message);
+        console.error("Add your Gemini key to ~/codedex/env/llm.env");
+        return;
+    }
+
+    const gemini = result.data;
+    console.log(\`GeminiManager ready: \${gemini.getKeyCount()} key(s)\`);
+
+    try {
+        const response = await gemini.execute(async (key) => {
+            console.log(\`Using key: \${key.substring(0, 8)}...\`);
+            // Replace with actual API call
+            return "Simulated API Response";
+        }, { maxRetries: 3, timeoutMs: 30000 });
+        console.log("Result:", response);
+    } catch (e: any) {
+        console.error("Failed:", e.message);
+    }
+}
+
+main();
+`;
         fs.writeFileSync(demoPath, tsCode);
-        console.log(`\x1b[92m[✔] Created demo.ts\x1b[0m`);
+        console.log(`\x1b[92m[+] Created demo.ts\x1b[0m`);
     } else {
-        console.log(`\x1b[90m[-] demo.ts already exists.\x1b[0m`);
+        console.log(`\x1b[90m[-] demo.ts already exists\x1b[0m`);
     }
 
-    console.log(`\n\x1b[93m🎉 Setup Complete!\x1b[0m`);
-    console.log(`To run the demo:`);
-    console.log(`\x1b[36m   npm install dotenv\x1b[0m`);
+    console.log(`\n\x1b[93mTo run the demo:\x1b[0m`);
     console.log(`\x1b[36m   npx ts-node demo.ts\x1b[0m\n`);
 }
 
-if (command === 'init') {
-    initProject();
-} else {
-    printDocs();
+switch (command) {
+    case 'init':
+        initProject();
+        break;
+    case 'setup':
+        setupEnvDir();
+        break;
+    case 'status':
+        showStatus();
+        break;
+    default:
+        printDocs();
 }

package/dist/env/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Centralized Environment Loader
+ * @module env
+ */
+export { loadCentralEnv, getCentralEnvVar, getDefaultEnvDir, } from './loader';
+export type { LoadCentralEnvOptions, LoadResult, } from './loader';

package/dist/env/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultEnvDir = exports.getCentralEnvVar = exports.loadCentralEnv = void 0;
+/**
+ * Centralized Environment Loader
+ * @module env
+ */
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "loadCentralEnv", { enumerable: true, get: function () { return loader_1.loadCentralEnv; } });
+Object.defineProperty(exports, "getCentralEnvVar", { enumerable: true, get: function () { return loader_1.getCentralEnvVar; } });
+Object.defineProperty(exports, "getDefaultEnvDir", { enumerable: true, get: function () { return loader_1.getDefaultEnvDir; } });
+//# sourceMappingURL=index.js.map

package/dist/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,mCAIkB;AAHd,wGAAA,cAAc,OAAA;AACd,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA"}

package/dist/env/loader.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Centralized Environment Loader
+ *
+ * Loads environment variables from ~/codedex/env/ so that all 35+ projects
+ * share a single source of truth for secrets. Portable via Google Drive.
+ *
+ * Directory structure:
+ *   ~/codedex/env/
+ *     common.env       — REDIS_URL, DATABASE_URL, shared across all projects
+ *     llm.env          — GEMINI_API_KEY, OPENAI_API_KEY (comma-separated or JSON arrays)
+ *     stripe.env       — STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
+ *     <custom>.env     — Any additional groupings
+ *
+ * @module env/loader
+ *
+ * @example
+ * ```ts
+ * // Load all env files from ~/codedex/env/
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv();
+ *
+ * // Now process.env has all the values
+ * console.log(process.env.GEMINI_API_KEY);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Load specific files only
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv({ files: ['llm.env', 'common.env'] });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom env directory (e.g., team-shared location)
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv({ envDir: '/shared/team/env' });
+ * ```
+ */
+export interface LoadCentralEnvOptions {
+    /**
+     * Path to the centralized env directory.
+     * Defaults to ~/codedex/env/
+     *
+     * Can also be set via CODEDEX_ENV_DIR environment variable.
+     */
+    envDir?: string;
+    /**
+     * Specific .env files to load (e.g., ['llm.env', 'common.env']).
+     * If omitted, loads ALL .env files in the directory.
+     */
+    files?: string[];
+    /**
+     * If true, central env values will NOT overwrite existing process.env values.
+     * Useful when a project needs to override a shared value locally.
+     * Default: false (central values take precedence over local .env)
+     */
+    preserveExisting?: boolean;
+    /**
+     * If true, silently continue when the env directory doesn't exist.
+     * If false, throw an error.
+     * Default: true (silent — for portability across dev environments)
+     */
+    silent?: boolean;
+}
+export interface LoadResult {
+    /** Whether the env directory was found and loaded */
+    loaded: boolean;
+    /** Path to the env directory that was used */
+    envDir: string;
+    /** List of .env files that were loaded */
+    filesLoaded: string[];
+    /** Number of environment variables set */
+    varsSet: number;
+    /** Variables that were skipped because they already existed (when preserveExisting=true) */
+    varsSkipped: string[];
+}
+/**
+ * Default env directory path: ~/codedex/env/
+ */
+export declare function getDefaultEnvDir(): string;
+/**
+ * Load environment variables from the centralized env directory into process.env.
+ *
+ * Call this once at the top of your app's entry point, before any code
+ * that reads process.env.
+ */
+export declare function loadCentralEnv(options?: LoadCentralEnvOptions): LoadResult;
+/**
+ * Read a single value from the centralized env without loading everything.
+ * Useful for one-off lookups.
+ */
+export declare function getCentralEnvVar(key: string, options?: {
+    envDir?: string;
+}): string | undefined;

package/dist/env/loader.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Centralized Environment Loader
+ *
+ * Loads environment variables from ~/codedex/env/ so that all 35+ projects
+ * share a single source of truth for secrets. Portable via Google Drive.
+ *
+ * Directory structure:
+ *   ~/codedex/env/
+ *     common.env       — REDIS_URL, DATABASE_URL, shared across all projects
+ *     llm.env          — GEMINI_API_KEY, OPENAI_API_KEY (comma-separated or JSON arrays)
+ *     stripe.env       — STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
+ *     <custom>.env     — Any additional groupings
+ *
+ * @module env/loader
+ *
+ * @example
+ * ```ts
+ * // Load all env files from ~/codedex/env/
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv();
+ *
+ * // Now process.env has all the values
+ * console.log(process.env.GEMINI_API_KEY);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Load specific files only
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv({ files: ['llm.env', 'common.env'] });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom env directory (e.g., team-shared location)
+ * import { loadCentralEnv } from '@splashcodex/api-key-manager/env';
+ * loadCentralEnv({ envDir: '/shared/team/env' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultEnvDir = getDefaultEnvDir;
+exports.loadCentralEnv = loadCentralEnv;
+exports.getCentralEnvVar = getCentralEnvVar;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const dotenv_1 = require("dotenv");
+// ─── Parser ──────────────────────────────────────────────────────────────────
+/**
+ * Parse a .env file content string into key-value pairs.
+ *
+ * Delegates to `dotenv.parse()` for battle-tested parsing that handles:
+ *   KEY=value
+ *   KEY="quoted value with spaces"
+ *   KEY='single quoted'
+ *   KEY=`backtick quoted`
+ *   MULTILINE="line1\nline2"  (real newlines inside double quotes)
+ *   KEY=value # inline comment
+ *   export KEY=value (bash-style)
+ *   # full-line comments
+ *   \n, \r, \t escape sequences
+ *
+ * Returns a Map<string, string> for compatibility with the rest of the loader.
+ */
+function parseEnvFile(content) {
+    const parsed = (0, dotenv_1.parse)(content);
+    return new Map(Object.entries(parsed));
+}
+// ─── Loader ──────────────────────────────────────────────────────────────────
+/**
+ * Default env directory path: ~/codedex/env/
+ */
+function getDefaultEnvDir() {
+    return process.env.CODEDEX_ENV_DIR || (0, path_1.join)((0, os_1.homedir)(), 'codedex', 'env');
+}
+/**
+ * Load environment variables from the centralized env directory into process.env.
+ *
+ * Call this once at the top of your app's entry point, before any code
+ * that reads process.env.
+ */
+function loadCentralEnv(options = {}) {
+    const envDir = options.envDir || getDefaultEnvDir();
+    const silent = options.silent !== false;
+    const preserveExisting = options.preserveExisting === true;
+    const result = {
+        loaded: false,
+        envDir,
+        filesLoaded: [],
+        varsSet: 0,
+        varsSkipped: [],
+    };
+    // Check if directory exists
+    if (!(0, fs_1.existsSync)(envDir)) {
+        if (!silent) {
+            throw new Error(`Centralized env directory not found: ${envDir}\n` +
+                `Create it with: mkdir -p ${envDir}\n` +
+                `Or set CODEDEX_ENV_DIR to point to your env directory.`);
+        }
+        return result;
+    }
+    // Determine which files to load
+    let filesToLoad;
+    if (options.files) {
+        filesToLoad = options.files;
+    }
+    else {
+        try {
+            filesToLoad = (0, fs_1.readdirSync)(envDir)
+                .filter(f => f.endsWith('.env'))
+                .sort(); // Alphabetical order for deterministic loading
+        }
+        catch {
+            if (!silent)
+                throw new Error(`Cannot read env directory: ${envDir}`);
+            return result;
+        }
+    }
+    // Load each file
+    for (const fileName of filesToLoad) {
+        const filePath = (0, path_1.join)(envDir, fileName);
+        if (!(0, fs_1.existsSync)(filePath)) {
+            if (!silent) {
+                throw new Error(`Env file not found: ${filePath}`);
+            }
+            continue;
+        }
+        try {
+            const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+            const vars = parseEnvFile(content);
+            for (const [key, value] of vars) {
+                if (preserveExisting && process.env[key] !== undefined) {
+                    result.varsSkipped.push(key);
+                    continue;
+                }
+                process.env[key] = value;
+                result.varsSet++;
+            }
+            result.filesLoaded.push(fileName);
+        }
+        catch (err) {
+            if (!silent)
+                throw err;
+        }
+    }
+    result.loaded = result.filesLoaded.length > 0;
+    return result;
+}
+/**
+ * Read a single value from the centralized env without loading everything.
+ * Useful for one-off lookups.
+ */
+function getCentralEnvVar(key, options) {
+    const envDir = options?.envDir || getDefaultEnvDir();
+    if (!(0, fs_1.existsSync)(envDir))
+        return undefined;
+    try {
+        const files = (0, fs_1.readdirSync)(envDir).filter(f => f.endsWith('.env')).sort();
+        for (const fileName of files) {
+            const content = (0, fs_1.readFileSync)((0, path_1.join)(envDir, fileName), 'utf-8');
+            const vars = parseEnvFile(content);
+            if (vars.has(key))
+                return vars.get(key);
+        }
+    }
+    catch {
+        // Silent fail
+    }
+    return undefined;
+}
+//# sourceMappingURL=loader.js.map

package/dist/env/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/env/loader.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,8 +6,10 @@
  * NEW in v5.0: Provider Presets (GeminiManager, OpenAIManager, MultiManager),
  *              Built-in Persistence (FileStorage, MemoryStorage)
  * Gemini-Specific: finishReason handling, Safety blocks, RECITATION detection
+ * Infrastructure: cockatiel (Bulkhead queueing + ExponentialBackoff w/ decorrelated jitter)
  */
 import { EventEmitter } from 'events';
+import { z } from 'zod';
 export { FileStorage } from './persistence/file';
 export type { FileStorageOptions } from './persistence/file';
 export { MemoryStorage } from './persistence/memory';
@@ -48,17 +50,19 @@ export interface ExecuteOptions {
     finishReason?: string;
     provider?: string;
 }
-export interface ApiKeyManagerOptions {
-    storage?: any;
-    strategy?: LoadBalancingStrategy;
-    fallbackFn?: () => any;
-    concurrency?: number;
-    semanticCache?: {
-        threshold?: number;
-        ttlMs?: number;
-        getEmbedding: (text: string) => Promise<number[]>;
-    };
-}
+export declare const ApiKeyManagerOptionsSchema: z.ZodObject<{
+    storage: z.ZodOptional<z.ZodAny>;
+    strategy: z.ZodOptional<z.ZodAny>;
+    fallbackFn: z.ZodOptional<z.ZodCustom<() => any, () => any>>;
+    concurrency: z.ZodOptional<z.ZodNumber>;
+    concurrencyQueueSize: z.ZodOptional<z.ZodNumber>;
+    semanticCache: z.ZodOptional<z.ZodObject<{
+        threshold: z.ZodOptional<z.ZodNumber>;
+        ttlMs: z.ZodOptional<z.ZodNumber>;
+        getEmbedding: z.ZodCustom<(text: string) => Promise<number[]>, (text: string) => Promise<number[]>>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+export type ApiKeyManagerOptions = z.infer<typeof ApiKeyManagerOptionsSchema>;
 export interface CacheEntry {
     vector: number[];
     prompt: string;
@@ -135,10 +139,11 @@ export declare class ApiKeyManager extends EventEmitter {
     private storage;
     private strategy;
     private fallbackFn?;
-    private maxConcurrency;
-    private activeCalls;
+    private bulkheadPolicy;
     private healthCheckFn?;
     private healthCheckInterval?;
+    private _saveTimer?;
+    private _saveDirty;
     private semanticCache?;
     private getEmbeddingFn?;
     private _isResolvingEmbedding;
@@ -175,6 +180,15 @@ export declare class ApiKeyManager extends EventEmitter {
     markSuccess(key: string, durationMs?: number): void;
     markFailed(key: string, classification: ErrorClassification): void;
     markFailedLegacy(key: string, isQuota?: boolean): void;
+    /**
+     * Calculate exponential backoff with decorrelated jitter using cockatiel.
+     * Decorrelated jitter avoids thundering-herd by randomizing retry intervals
+     * independent of the previous delay, which is statistically superior to
+     * simple `random * exponential` jitter.
+     *
+     * @param attempt - Zero-indexed attempt number
+     */
+    private readonly _backoffFactory;
     calculateBackoff(attempt: number): number;
     getStats(): ApiKeyManagerStats;
     _getKeys(): KeyState[];
@@ -205,6 +219,11 @@ export declare class ApiKeyManager extends EventEmitter {
     executeStream<T>(fn: (key: string, signal?: AbortSignal) => AsyncGenerator<T, any, unknown>, options?: ExecuteOptions & {
         prompt?: string;
     }): AsyncGenerator<T, any, unknown>;
+    /**
+     * Helper: stores result in semantic cache then returns it.
+     * Called by the bulkhead execute() callback and the no-bulkhead path.
+     */
+    private _executeWithSemanticAndRetry;
     private _executeWithRetry;
     private _executeWithTimeout;
     private _sleep;
@@ -222,6 +241,17 @@ export declare class ApiKeyManager extends EventEmitter {
      */
     stopHealthChecks(): void;
     private _runHealthChecks;
+    /**
+     * Debounced save — marks state as dirty and flushes after 500ms of inactivity.
+     * Under heavy load (multiple getKey/markSuccess/markFailed calls), this coalesces
+     * dozens of writeFileSync calls into one.
+     */
     private saveState;
+    /**
+     * Immediately flush state to storage. Called by the debounce timer
+     * and by stopHealthChecks() to ensure clean shutdown.
+     */
+    flushState(): void;
+    private _flushState;
     private loadState;
 }