opencode-free-fleet 0.1.0 → 0.2.1

package/dist/core/oracle.js

@@ -0,0 +1,234 @@
+/**
+ * Metadata Oracle - Cross-Provider Model Metadata Lookup
+ *
+ * v0.2.1 - Build Repair: Removed problematic Z.Ai SDK import
+ */
+/**
+ * Static knowledge base of confirmed free models
+ * This can be updated without code changes
+ */
+export const CONFIRMED_FREE_MODELS = new Set([
+    // OpenRouter (verified free via pricing)
+    'openrouter/qwen/qwen3-coder:free',
+    'openrouter/deepseek/deepseek-v3.2',
+    'openrouter/deepseek/deepseek-r1-0528:free',
+    'openrouter/z-ai/glm-4.5-air:free',
+    'openrouter/arcee-ai/trinity-large-preview:free',
+    'openrouter/mistralai/mistral-small-3.1-24b-instruct:free',
+    'openrouter/mistralai/mistral-tiny:free',
+    'openrouter/nvidia/nemotron-3-nano-30b-a3b:free',
+    'openrouter/nvidia/nemotron-3-nano-12b-v2-vl:free',
+    'openrouter/nvidia/nemotron-3-nano-9b-v2:free',
+    'openrouter/google/gemma-3n-e2b-it:free',
+    'openrouter/google/gemma-3n-e4b-it:free',
+    // DeepSeek (official documentation)
+    'deepseek/deepseek-chat',
+    'deepseek/deepseek-v3',
+    'deepseek/deepseek-r1',
+    // Groq (current policy)
+    'groq/llama-3.1-8b-instruct',
+    'groq/llama-3.1-70b-versatile-instruct',
+    'groq/mixtral-8x7b-instruct',
+    // Hugging Face (serverless free tier)
+    'huggingface/Qwen/Qwen2.5-72B-Instruct-Turbo',
+    // Google (limited free tier)
+    'google/gemini-1.5-flash',
+    'google/gemini-1.5-flash-8b'
+]);
+/**
+ * External metadata APIs
+ * Source for free tier verification
+ */
+const METADATA_SOURCES = [
+    'models.dev' // Open source model metadata database
+];
+/**
+ * Models.dev metadata API client
+ */
+class ModelsDevAdapter {
+    providerId = 'models.dev';
+    providerName = 'Models.dev';
+    async fetchModelsMetadata(modelIds) {
+        if (modelIds && modelIds.length === 0) {
+            console.log('📊 Models.dev: No model IDs provided, fetching all known free models');
+        }
+        const all = await this._fetchFromModelsDev();
+        return modelIds ? all.filter(m => modelIds.includes(m.id)) : all;
+    }
+    async fetchModelMetadata(modelId) {
+        const all = await this._fetchFromModelsDev();
+        const model = all.find(m => m.id === modelId);
+        if (!model) {
+            return {
+                id: modelId,
+                provider: this.providerId,
+                name: modelId,
+                isFree: false,
+                confidence: 0,
+                reason: 'Model not found in Models.dev',
+                pricing: { prompt: '0', completion: '0', request: '0' }
+            };
+        }
+        // Determine if free based on Models.dev data
+        const isFree = model.pricing?.prompt === '0' || model.pricing?.prompt === '0.0' ||
+            model.pricing?.completion === '0' || model.pricing?.completion === '0.0';
+        return {
+            id: model.id,
+            provider: this.providerId,
+            name: model.name || model.id,
+            isFree,
+            confidence: isFree ? 1.0 : 0.7,
+            reason: isFree ? `Confirmed free via Models.dev (prompt=${model.pricing?.prompt}, completion=${model.pricing?.completion})` : 'Uncertain pricing - SDK may differ',
+            lastVerified: new Date().toISOString(),
+            pricing: {
+                prompt: model.pricing?.prompt || '0',
+                completion: model.pricing?.completion || '0',
+                request: model.pricing?.request || '0'
+            }
+        };
+    }
+    async _fetchFromModelsDev() {
+        console.log('📊 Models.dev: Fetching model metadata...');
+        try {
+            const response = await fetch('https://models.dev/api/v1/models', {
+                headers: {
+                    'Accept': 'application/json'
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`Models.dev API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            const models = data.data || [];
+            console.log(`✓ Models.dev: Found ${models.length} models`);
+            return models;
+        }
+        catch (error) {
+            console.error('❌ Models.dev API error:', error);
+            return [];
+        }
+    }
+    isAvailable() {
+        // Always available (public API)
+        return true;
+    }
+}
+/**
+ * Unified metadata oracle
+ * Aggregates data from multiple metadata sources
+ */
+export class MetadataOracle {
+    adapters = new Map();
+    constructor() {
+        this._initializeAdapters();
+    }
+    /**
+     * Initialize all metadata adapters
+     */
+    _initializeAdapters() {
+        console.log('🔮 Metadata Oracle: Initializing adapters...');
+        // Models.dev - Always available
+        this.adapters.set('models.dev', new ModelsDevAdapter());
+        // Note: Removed Z.Ai SDK, Google Cloud AI SDK, etc.
+        // These adapters are now implemented directly in src/core/adapters/index.ts
+    }
+    /**
+     * Check which adapters are available
+     */
+    getAvailableAdapters() {
+        const available = [];
+        for (const [providerId, adapter] of this.adapters.entries()) {
+            if (adapter.isAvailable()) {
+                available.push(providerId);
+            }
+        }
+        return available;
+    }
+    /**
+     * Fetch metadata for a specific model from all available sources
+     * This is the main method Scout should call for free tier detection
+     */
+    async fetchModelMetadata(modelId) {
+        console.log(`\n🔮 Metadata Oracle: Fetching metadata for ${modelId}...\n`);
+        const availableAdapters = this.getAvailableAdapters();
+        const allMetadata = [];
+        // Try each available adapter
+        for (const providerId of availableAdapters) {
+            const adapter = this.adapters.get(providerId);
+            if (!adapter)
+                continue;
+            try {
+                const metadata = await adapter.fetchModelMetadata(modelId);
+                allMetadata.push(metadata);
+            }
+            catch (error) {
+                console.warn(`⚠️  Metadata Oracle: Adapter ${providerId} failed: ${error}`);
+            }
+        }
+        if (allMetadata.length === 0) {
+            return {
+                id: modelId,
+                provider: 'unknown',
+                name: modelId,
+                isFree: false,
+                confidence: 0,
+                reason: 'Model not found in any metadata source',
+                pricing: { prompt: '0', completion: '0', request: '0' }
+            };
+        }
+        // Merge results with confidence scoring
+        const freeResults = allMetadata.filter(m => m.isFree);
+        const hasFreeResult = freeResults.length > 0;
+        // Determine overall confidence
+        let confidence = 0.3; // Low confidence if no metadata
+        let reason = 'No metadata found';
+        if (hasFreeResult) {
+            confidence = 1.0; // High confidence if at least one source says free
+            reason = `Confirmed free by ${freeResults.map(m => m.provider).join(', ')}`;
+        }
+        else if (allMetadata.length > 0) {
+            confidence = 0.7; // Medium confidence if metadata exists but no free result
+            reason = `Metadata found but not confirmed free (providers: ${allMetadata.map(m => m.provider).join(', ')})`;
+        }
+        // Return first free result (highest confidence)
+        const finalMetadata = hasFreeResult ? freeResults[0] : allMetadata[0];
+        return {
+            ...finalMetadata,
+            confidence,
+            reason,
+            lastVerified: new Date().toISOString()
+        };
+    }
+    /**
+     * Batch fetch metadata for multiple models
+     */
+    async fetchModelsMetadata(modelIds) {
+        console.log(`\n🔮 Metadata Oracle: Fetching metadata for ${modelIds.length} models...\n`);
+        const availableAdapters = this.getAvailableAdapters();
+        const allMetadata = [];
+        for (const modelId of modelIds) {
+            const metadata = await this.fetchModelMetadata(modelId);
+            allMetadata.push(metadata);
+        }
+        return allMetadata;
+    }
+    /**
+     * Get list of all confirmed free models
+     */
+    getConfirmedFreeModels() {
+        return CONFIRMED_FREE_MODELS;
+    }
+    /**
+     * Add a manually confirmed free model
+     * This allows updating of static knowledge base
+     */
+    addConfirmedFreeModel(modelId) {
+        CONFIRMED_FREE_MODELS.add(modelId);
+    }
+    /**
+     * Remove a model from confirmed free list
+     */
+    removeConfirmedFreeModel(modelId) {
+        CONFIRMED_FREE_MODELS.delete(modelId);
+    }
+}

package/dist/core/racer.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The Racer - Zero-Latency Model Competition
+ *
+ * This module implements Promise.any-based racing between multiple free models,
+ * accepting the first valid response. This eliminates waterfall latency
+ * and optimizes for zero-cost execution.
+ *
+ * Key Features:
+ * - Promise.any for race condition
+ * - AbortController for timeout handling
+ * - Progress callbacks for monitoring
+ * - Error aggregation for all failures
+ */
+import type { RaceResult, RaceConfig } from '../types/index.js';
+/**
+ * Racer class for competing free models
+ */
+export declare class FreeModelRacer {
+    private config;
+    private activeRaces;
+    constructor(config?: RaceConfig);
+    /**
+     * Compete between multiple free models and return the fastest valid response
+     * Uses Promise.any for race condition - fires all requests simultaneously
+     * and accepts the first valid response.
+     *
+     * @param models - Array of model identifiers to compete
+     * @param executeWithModel - Function to execute task with a specific model
+     * @param raceId - Optional ID for tracking and cancellation
+     * @returns Object containing the winning model and its result
+     *
+     * @example
+     * ```typescript
+     * const racer = new FreeModelRacer({ timeoutMs: 15000 });
+     *
+     * const models = [
+     *   'deepseek/deepseek-v3.2',
+     *   'zai-coding-plan/glm-4.7-flash',
+     *   'openrouter/mistralai/mistral-small-3.1-24b-instruct:free'
+     * ];
+     *
+     * const winner = await racer.race(
+     *   models,
+     *   async (model) => {
+     *     return await client.chat.completions.create({ model, messages });
+     *   },
+     *   'session-123'
+     * );
+     *
+     * console.log(`Fastest: ${winner.model} (${winner.duration}ms)`);
+     * return winner.result;
+     * ```
+     */
+    race<T>(models: string[], executeWithModel: (model: string) => Promise<T>, raceId?: string): Promise<RaceResult<T>>;
+    /**
+     * Race models from a category config
+     */
+    raceFromCategory<T>(categoryConfig: {
+        model: string;
+        fallback: string[];
+    }, executeWithModel: (model: string) => Promise<T>, raceId?: string): Promise<RaceResult<T>>;
+    /**
+     * Cancel an active race by ID
+     */
+    cancelRace(raceId: string): boolean;
+    /**
+     * Cancel all active races
+     */
+    cancelAllRaces(): void;
+    /**
+     * Get count of active races
+     */
+    getActiveRaceCount(): number;
+    /**
+     * Check if a race is currently active
+     */
+    isRaceActive(raceId: string): boolean;
+    /**
+     * Create a timeout promise that rejects when abort signal is received
+     */
+    private createTimeoutPromise;
+    /**
+     * Update race configuration
+     */
+    updateConfig(config: Partial<RaceConfig>): void;
+    /**
+     * Get current race configuration
+     */
+    getConfig(): Readonly<RaceConfig>;
+}
+/**
+ * Compete between multiple free models (convenience function)
+ *
+ * This is a stateless version of FreeModelRacer for simple one-off races.
+ *
+ * @param models - Array of model identifiers to compete
+ * @param executeWithModel - Function to execute task with a specific model
+ * @param config - Optional race configuration
+ * @returns Object containing the winning model and its result
+ */
+export declare function competeFreeModels<T>(models: string[], executeWithModel: (model: string) => Promise<T>, config?: RaceConfig): Promise<RaceResult<T>>;
+/**
+ * Create a new Racer instance with optional config
+ */
+export declare function createRacer(config?: RaceConfig): FreeModelRacer;

package/dist/core/racer.js

@@ -0,0 +1,209 @@
+/**
+ * The Racer - Zero-Latency Model Competition
+ *
+ * This module implements Promise.any-based racing between multiple free models,
+ * accepting the first valid response. This eliminates waterfall latency
+ * and optimizes for zero-cost execution.
+ *
+ * Key Features:
+ * - Promise.any for race condition
+ * - AbortController for timeout handling
+ * - Progress callbacks for monitoring
+ * - Error aggregation for all failures
+ */
+/**
+ * Racer class for competing free models
+ */
+export class FreeModelRacer {
+    config;
+    activeRaces = new Map();
+    constructor(config = {}) {
+        this.config = {
+            timeoutMs: 30000,
+            ...config
+        };
+    }
+    /**
+     * Compete between multiple free models and return the fastest valid response
+     * Uses Promise.any for race condition - fires all requests simultaneously
+     * and accepts the first valid response.
+     *
+     * @param models - Array of model identifiers to compete
+     * @param executeWithModel - Function to execute task with a specific model
+     * @param raceId - Optional ID for tracking and cancellation
+     * @returns Object containing the winning model and its result
+     *
+     * @example
+     * ```typescript
+     * const racer = new FreeModelRacer({ timeoutMs: 15000 });
+     *
+     * const models = [
+     *   'deepseek/deepseek-v3.2',
+     *   'zai-coding-plan/glm-4.7-flash',
+     *   'openrouter/mistralai/mistral-small-3.1-24b-instruct:free'
+     * ];
+     *
+     * const winner = await racer.race(
+     *   models,
+     *   async (model) => {
+     *     return await client.chat.completions.create({ model, messages });
+     *   },
+     *   'session-123'
+     * );
+     *
+     * console.log(`Fastest: ${winner.model} (${winner.duration}ms)`);
+     * return winner.result;
+     * ```
+     */
+    async race(models, executeWithModel, raceId = `race-${Date.now()}`) {
+        if (models.length === 0) {
+            throw new Error('Racer: No models provided for competition');
+        }
+        console.log(`🏁 Racer: Starting race '${raceId}' with ${models.length} models`);
+        // Create abort controller for this race
+        const abortController = new AbortController();
+        this.activeRaces.set(raceId, abortController);
+        const startTime = performance.now();
+        try {
+            const racePromises = models.map(async (model) => {
+                try {
+                    // Notify started
+                    this.config.onProgress?.(model, 'started');
+                    const result = await Promise.race([
+                        executeWithModel(model),
+                        this.createTimeoutPromise(this.config.timeoutMs, abortController.signal)
+                    ]);
+                    const duration = performance.now() - startTime;
+                    // Notify completed
+                    this.config.onProgress?.(model, 'completed');
+                    console.log(`✅ Racer: ${model} completed in ${duration.toFixed(0)}ms`);
+                    return { model, result, duration };
+                }
+                catch (error) {
+                    const err = error;
+                    // Notify failed
+                    this.config.onProgress?.(model, 'failed', err);
+                    // Check if aborted
+                    if (err.name === 'AbortError') {
+                        console.log(`⏹️  Racer: ${model} aborted`);
+                    }
+                    else {
+                        console.log(`❌ Racer: ${model} failed - ${err.message}`);
+                    }
+                    throw new Error(`Model ${model} failed: ${err.message}`);
+                }
+            });
+            const winner = await Promise.any(racePromises);
+            // Abort all other pending requests
+            abortController.abort();
+            this.activeRaces.delete(raceId);
+            console.log(`🏆 Racer: Winner is ${winner.model} (${winner.duration.toFixed(0)}ms)`);
+            console.log(`   Competed against: ${models.join(', ')}`);
+            return winner;
+        }
+        catch (error) {
+            // Clean up
+            this.activeRaces.delete(raceId);
+            // AggregateError: all models failed
+            const err = error;
+            if (err.name === 'AggregateError' && err.errors) {
+                const errorDetails = err.errors.map((e) => e.message).join('\n');
+                throw new Error(`Racer: All ${models.length} models failed:\n${errorDetails}`);
+            }
+            // Check if race was externally aborted
+            if (err.name === 'AbortError') {
+                console.log(`🛑 Racer: Race '${raceId}' externally aborted`);
+                throw new Error(`was aborted`);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Race models from a category config
+     */
+    async raceFromCategory(categoryConfig, executeWithModel, raceId) {
+        const allModels = [categoryConfig.model, ...categoryConfig.fallback];
+        return this.race(allModels, executeWithModel, raceId);
+    }
+    /**
+     * Cancel an active race by ID
+     */
+    cancelRace(raceId) {
+        const controller = this.activeRaces.get(raceId);
+        if (controller) {
+            controller.abort();
+            this.activeRaces.delete(raceId);
+            console.log(`🛑 Racer: Cancelled race '${raceId}'`);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Cancel all active races
+     */
+    cancelAllRaces() {
+        for (const [raceId, controller] of this.activeRaces.entries()) {
+            controller.abort();
+            console.log(`🛑 Racer: Cancelled race '${raceId}'`);
+        }
+        this.activeRaces.clear();
+    }
+    /**
+     * Get count of active races
+     */
+    getActiveRaceCount() {
+        return this.activeRaces.size;
+    }
+    /**
+     * Check if a race is currently active
+     */
+    isRaceActive(raceId) {
+        return this.activeRaces.has(raceId);
+    }
+    /**
+     * Create a timeout promise that rejects when abort signal is received
+     */
+    createTimeoutPromise(timeoutMs, signal) {
+        return new Promise((_, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error('Timeout'));
+            }, timeoutMs);
+            signal.addEventListener('abort', () => {
+                clearTimeout(timeout);
+                reject(new Error('AbortError'));
+            }, { once: true });
+        });
+    }
+    /**
+     * Update race configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current race configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Compete between multiple free models (convenience function)
+ *
+ * This is a stateless version of FreeModelRacer for simple one-off races.
+ *
+ * @param models - Array of model identifiers to compete
+ * @param executeWithModel - Function to execute task with a specific model
+ * @param config - Optional race configuration
+ * @returns Object containing the winning model and its result
+ */
+export async function competeFreeModels(models, executeWithModel, config) {
+    const racer = new FreeModelRacer(config);
+    return racer.race(models, executeWithModel);
+}
+/**
+ * Create a new Racer instance with optional config
+ */
+export function createRacer(config) {
+    return new FreeModelRacer(config);
+}

package/dist/core/scout.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The Scout - Multi-Provider Free Model Discovery & Benchmark-Based Ranking
+ *
+ * v0.2.0 Upgrade: Metadata Oracle + Smart Free Tier Detection
+ *
+ * This module discovers free LLM models from ALL connected providers,
+ * aggregates metadata from external APIs, and ranks them by SOTA benchmark performance.
+ */
+import type { ScoutConfig, ScoutResult, ModelCategory } from '../types/index.js';
+/**
+ * Scout class for model discovery and ranking
+ */
+export declare class Scout {
+    private config;
+    private blocklist;
+    private antigravityActive;
+    private metadataOracle;
+    constructor(config?: Partial<ScoutConfig>);
+    /**
+     * Initialize metadata oracle and adapters
+     */
+    private initialize;
+    /**
+     * PHASE A: Safety Check - Build blocklist of paid/authenticated models
+     *
+     * Enhanced in v0.2.0:
+     * - Check for Antigravity auth presence/configuration
+     * - Respect allowAntigravity flag to optionally include Google/Gemini
+     * - NOTE: Blocklist is now used for metadata filtering, not model exclusion
+     */
+    private buildBlocklist;
+    /**
+     * Detect active providers from OpenCode configuration
+     */
+    private detectActiveProviders;
+    /**
+     * PHASE B: Fetch and Normalize Models with Metadata Oracle
+     *
+     * Enhanced in v0.2.0:
+     * - Fetch models from provider adapters
+     * - Enrich with metadata from MetadataOracle (Models.dev)
+     * - Determine free tier based on aggregated metadata + confidence scoring
+     * - Use metadata.isFree field instead of hardcoded free tier detection
+     */
+    private fetchAllModels;
+    /**
+     * Categorize a model based on its ID patterns
+     */
+    private categorizeModel;
+    /**
+     * Check if a model is in Elite families
+     */
+    private isEliteModel;
+    /**
+     * Extract parameter count from model ID
+     * Looks for patterns like "70b", "8b", "32b" in the ID
+     */
+    private extractParams;
+    /**
+     * Extract date from model ID (if available)
+     * Looks for patterns like "2025-01", "v0.1" in the ID
+     */
+    private extractDate;
+    /**
+     * Get provider priority from metadata
+     * Higher priority providers are listed first in OpenCode settings
+     */
+    private getProviderPriority;
+    /**
+     * Get elite patterns for a specific category
+     */
+    private _getElitePatterns;
+    /**
+     * PHASE C: Ranking Algorithm - Multi-Provider SOTA Benchmarking
+     *
+     * Enhanced in v0.2.0:
+     * - Priority 1: Metadata confidence score (from Models.dev, etc.)
+     * - Priority 2: Elite family membership (SOTA benchmarks)
+     * - Priority 3: Provider priority (from metadata provider ranking)
+     * - Priority 4: Parameter count (larger > smaller, except for speed)
+     * - Priority 5: Release date (newer > older)
+     * - Priority 6: Alphabetical order (tiebreaker)
+     */
+    private rankModelsByBenchmark;
+    /**
+     * PHASE D: Functional Categorization
+     *
+     * Sorts models into functional categories based on ID patterns:
+     * - coding: IDs with "coder", "code", "function"
+     * - reasoning: IDs with "r1", "reasoning", "cot", "qwq"
+     * - speed: IDs with "flash", "distill", "nano", "lite"
+     * - multimodal: IDs with "vl", "vision"
+     * - writing: General purpose models not in other categories
+     */
+    private categorizeModels;
+    /**
+     * Generate category configuration from ranked models
+     */
+    private generateCategoryConfig;
+    /**
+     * Main discovery and ranking method
+     * Returns categorized and ranked free models from ALL active providers
+     * with metadata enrichment from external APIs
+     */
+    discover(): Promise<Record<ModelCategory, ScoutResult>>;
+    /**
+     * Print summary of results
+     */
+    printSummary(results: Record<ModelCategory, ScoutResult>): void;
+    /**
+     * Get configuration info
+     */
+    getConfiguration(): Promise<{
+        antigravityActive: boolean;
+        allowAntigravity: boolean;
+        blocklist: string[];
+        hasMetadataOracle: boolean;
+        providersAvailable?: string[];
+    }>;
+}
+/**
+ * Create a new Scout instance with optional config
+ */
+export declare function createScout(config?: Partial<ScoutConfig>): Scout;