whale-code 6.4.0

package/dist/server/lib/provider-capabilities.js

@@ -0,0 +1,190 @@
+/**
+ * Provider Capability Matrix — static feature map for intelligent request routing.
+ *
+ * Each provider declares which features it supports. This enables:
+ * - Pre-flight checks before sending a request to a provider
+ * - Capability-aware failover (don't fail over to a provider that can't handle the request)
+ * - Intelligent routing (pick the best provider for a given request shape)
+ */
+// ============================================================================
+// CAPABILITY MAP — static, no runtime computation
+// ============================================================================
+const PROVIDER_CAPABILITIES = {
+    anthropic: {
+        vision: true,
+        pdf: true,
+        computerUse: true,
+        codeExecution: false,
+        streaming: true,
+        batchApi: true,
+        citations: true,
+        thinking: true,
+        toolUse: true,
+        caching: true,
+        contextManagement: true,
+        maxContextTokens: 200_000,
+        maxOutputTokens: 128_000,
+    },
+    openai: {
+        vision: true,
+        pdf: false,
+        computerUse: false,
+        codeExecution: true,
+        streaming: true,
+        batchApi: true,
+        citations: false,
+        thinking: true,
+        toolUse: true,
+        caching: true,
+        contextManagement: false,
+        maxContextTokens: 128_000,
+        maxOutputTokens: 128_000,
+    },
+    gemini: {
+        vision: true,
+        pdf: true,
+        computerUse: false,
+        codeExecution: true,
+        streaming: true,
+        batchApi: false,
+        citations: false,
+        thinking: true,
+        toolUse: true,
+        caching: true,
+        contextManagement: false,
+        maxContextTokens: 1_000_000,
+        maxOutputTokens: 65_536,
+    },
+    bedrock: {
+        vision: true,
+        pdf: true,
+        computerUse: true,
+        codeExecution: false,
+        streaming: true,
+        batchApi: false,
+        citations: true,
+        thinking: true,
+        toolUse: true,
+        caching: false,
+        contextManagement: false,
+        maxContextTokens: 200_000,
+        maxOutputTokens: 64_000,
+    },
+};
+// ============================================================================
+// QUERY FUNCTIONS
+// ============================================================================
+/**
+ * Get the full capability set for a provider.
+ * Returns a defensive copy so callers can't mutate the static map.
+ */
+export function getCapabilities(provider) {
+    const caps = PROVIDER_CAPABILITIES[provider];
+    if (!caps) {
+        throw new Error(`Unknown provider: "${provider}". Known: ${Object.keys(PROVIDER_CAPABILITIES).join(", ")}`);
+    }
+    return { ...caps };
+}
+/**
+ * Check if a provider supports a specific boolean feature.
+ */
+export function supportsFeature(provider, feature) {
+    const caps = PROVIDER_CAPABILITIES[provider];
+    if (!caps)
+        return false;
+    return caps[feature] === true;
+}
+/**
+ * Find all providers that support a given boolean feature.
+ * Returns provider names sorted with anthropic first (default preference).
+ */
+export function findProvidersWithCapability(feature) {
+    const preferred = ["anthropic", "openai", "gemini", "bedrock"];
+    return preferred.filter((p) => {
+        const caps = PROVIDER_CAPABILITIES[p];
+        return caps && caps[feature] === true;
+    });
+}
+/**
+ * Determine the best provider for a request based on its capability requirements.
+ *
+ * Strategy:
+ * 1. Filter to providers that satisfy ALL required capabilities
+ * 2. Prefer Anthropic as default
+ * 3. Among remaining candidates, prefer the one with the largest context window
+ *
+ * Returns "anthropic" as fallback if no provider matches all requirements
+ * (better to attempt than to hard-fail — the provider will return a clear error).
+ */
+export function getBestProviderForRequest(request, excludeProviders) {
+    const allProviders = ["anthropic", "openai", "gemini", "bedrock"];
+    const candidates = allProviders.filter((provider) => {
+        if (excludeProviders?.has(provider))
+            return false;
+        const caps = PROVIDER_CAPABILITIES[provider];
+        if (!caps)
+            return false;
+        // Check boolean requirements
+        if (request.hasImages && !caps.vision)
+            return false;
+        if (request.hasPdf && !caps.pdf)
+            return false;
+        if (request.needsBatch && !caps.batchApi)
+            return false;
+        if (request.needsCitations && !caps.citations)
+            return false;
+        if (request.needsComputerUse && !caps.computerUse)
+            return false;
+        if (request.needsCodeExecution && !caps.codeExecution)
+            return false;
+        if (request.needsThinking && !caps.thinking)
+            return false;
+        if (request.needsContextManagement && !caps.contextManagement)
+            return false;
+        // Check numeric requirements
+        if (request.minContextTokens && caps.maxContextTokens < request.minContextTokens)
+            return false;
+        if (request.minOutputTokens && caps.maxOutputTokens < request.minOutputTokens)
+            return false;
+        return true;
+    });
+    if (candidates.length === 0) {
+        // No provider matches all requirements — fall back to anthropic
+        return "anthropic";
+    }
+    // Prefer anthropic if it's among candidates
+    if (candidates.includes("anthropic"))
+        return "anthropic";
+    // Otherwise return the first candidate (ordered by preference: openai, gemini, bedrock)
+    return candidates[0];
+}
+/**
+ * Check if a provider can handle a request with the given requirements.
+ * Returns true if all requirements are met.
+ */
+export function canProviderHandleRequest(provider, requirements) {
+    const caps = PROVIDER_CAPABILITIES[provider];
+    if (!caps)
+        return false;
+    if (requirements.hasImages && !caps.vision)
+        return false;
+    if (requirements.hasPdf && !caps.pdf)
+        return false;
+    if (requirements.needsBatch && !caps.batchApi)
+        return false;
+    if (requirements.needsCitations && !caps.citations)
+        return false;
+    if (requirements.needsComputerUse && !caps.computerUse)
+        return false;
+    if (requirements.needsCodeExecution && !caps.codeExecution)
+        return false;
+    if (requirements.needsThinking && !caps.thinking)
+        return false;
+    if (requirements.needsContextManagement && !caps.contextManagement)
+        return false;
+    if (requirements.minContextTokens && caps.maxContextTokens < requirements.minContextTokens)
+        return false;
+    if (requirements.minOutputTokens && caps.maxOutputTokens < requirements.minOutputTokens)
+        return false;
+    return true;
+}

package/dist/server/lib/provider-failover.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider Failover Chain — Phase 4.1
+ *
+ * Manages provider health and automatic failover routing.
+ * If a provider accumulates 3 consecutive failures within 5 minutes,
+ * it is marked degraded and requests are routed to the next healthy
+ * provider in the chain. Degraded providers are re-checked every 60s.
+ */
+import { type RequestCapabilityRequirements } from "./provider-capabilities.js";
+export interface ProviderHealth {
+    name: string;
+    status: "healthy" | "degraded";
+    consecutiveFailures: number;
+    lastFailure: number;
+    degradedAt: number;
+}
+export interface FailoverEvent {
+    timestamp: number;
+    originalProvider: string;
+    fallbackProvider: string;
+    reason: string;
+}
+export declare class ProviderFailover {
+    private providers;
+    private chain;
+    private recoveryTimer;
+    private auditLog;
+    constructor(chain: string[]);
+    /**
+     * Returns the provider (and optionally a fallback model) to use.
+     * If the requested provider is healthy, returns it as-is.
+     * If degraded, walks the chain to find the next healthy provider
+     * and returns a sensible fallback model for that provider.
+     *
+     * When requiredCapabilities is provided, failover candidates that lack
+     * the required capabilities are skipped — prevents routing a PDF request
+     * to a provider that doesn't support PDFs, for example.
+     */
+    getActiveProvider(requestedModel: string, requiredCapabilities?: RequestCapabilityRequirements): {
+        provider: string;
+        model: string;
+        failedOver: boolean;
+        originalProvider: string;
+    };
+    /**
+     * Record a successful API call — resets consecutive failures and
+     * marks the provider healthy if it was degraded.
+     */
+    recordSuccess(provider: string): void;
+    /**
+     * Record a failed API call — increments consecutive failures.
+     * If threshold is reached within the failure window, marks degraded.
+     */
+    recordFailure(provider: string): void;
+    /**
+     * Start the recovery loop — checks degraded providers every 60s.
+     * Resets them to healthy so the next request can attempt them.
+     * If the attempt fails, recordFailure will re-degrade immediately.
+     */
+    startRecoveryLoop(): void;
+    /**
+     * Stop the recovery loop (for clean shutdown / testing).
+     */
+    stopRecoveryLoop(): void;
+    /**
+     * Get current health status of all providers.
+     */
+    getStatus(): ProviderHealth[];
+    /**
+     * Get the failover audit log.
+     */
+    getAuditLog(): FailoverEvent[];
+}
+export declare const providerFailover: ProviderFailover;

package/dist/server/lib/provider-failover.js

@@ -0,0 +1,210 @@
+/**
+ * Provider Failover Chain — Phase 4.1
+ *
+ * Manages provider health and automatic failover routing.
+ * If a provider accumulates 3 consecutive failures within 5 minutes,
+ * it is marked degraded and requests are routed to the next healthy
+ * provider in the chain. Degraded providers are re-checked every 60s.
+ */
+import { getProvider } from "../../shared/constants.js";
+import { canProviderHandleRequest } from "./provider-capabilities.js";
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const DEGRADATION_THRESHOLD = 3; // consecutive failures to mark degraded
+const FAILURE_WINDOW_MS = 5 * 60 * 1000; // 5 minutes — failures outside this window don't count
+const RECOVERY_CHECK_MS = 60 * 1000; // 60 seconds — how often to auto-recover degraded providers
+// Default fallback model mapping — when a provider is degraded, use the
+// equivalent-tier model from the fallback provider.
+const FALLBACK_MODELS = {
+    // If anthropic is down, which openai/gemini model to use
+    anthropic: {
+        openai: "gpt-5",
+        gemini: "gemini-2.5-pro",
+    },
+    // If openai is down, which anthropic/gemini model to use
+    openai: {
+        anthropic: "claude-sonnet-4-6",
+        gemini: "gemini-2.5-pro",
+    },
+    // If gemini is down, which anthropic/openai model to use
+    gemini: {
+        anthropic: "claude-sonnet-4-6",
+        openai: "gpt-5",
+    },
+};
+// ============================================================================
+// PROVIDER FAILOVER CLASS
+// ============================================================================
+export class ProviderFailover {
+    providers;
+    chain;
+    recoveryTimer = null;
+    auditLog = [];
+    constructor(chain) {
+        this.chain = chain;
+        this.providers = new Map();
+        for (const name of chain) {
+            this.providers.set(name, {
+                name,
+                status: "healthy",
+                consecutiveFailures: 0,
+                lastFailure: 0,
+                degradedAt: 0,
+            });
+        }
+    }
+    /**
+     * Returns the provider (and optionally a fallback model) to use.
+     * If the requested provider is healthy, returns it as-is.
+     * If degraded, walks the chain to find the next healthy provider
+     * and returns a sensible fallback model for that provider.
+     *
+     * When requiredCapabilities is provided, failover candidates that lack
+     * the required capabilities are skipped — prevents routing a PDF request
+     * to a provider that doesn't support PDFs, for example.
+     */
+    getActiveProvider(requestedModel, requiredCapabilities) {
+        const originalProvider = getProvider(requestedModel);
+        const health = this.providers.get(originalProvider);
+        // If provider is healthy (or unknown to chain), use as-is
+        if (!health || health.status === "healthy") {
+            return {
+                provider: originalProvider,
+                model: requestedModel,
+                failedOver: false,
+                originalProvider,
+            };
+        }
+        // Provider is degraded — find next healthy in chain
+        const chainIndex = this.chain.indexOf(originalProvider);
+        for (let offset = 1; offset < this.chain.length; offset++) {
+            const candidateIndex = (chainIndex + offset) % this.chain.length;
+            const candidateName = this.chain[candidateIndex];
+            const candidateHealth = this.providers.get(candidateName);
+            if (candidateHealth && candidateHealth.status === "healthy") {
+                // Skip candidates that can't handle the request's required capabilities
+                if (requiredCapabilities &&
+                    !canProviderHandleRequest(candidateName, requiredCapabilities)) {
+                    console.log(`[failover] Skipping ${candidateName} — lacks required capabilities`);
+                    continue;
+                }
+                // Map to a fallback model for the candidate provider
+                const fallbackModel = FALLBACK_MODELS[originalProvider]?.[candidateName] || requestedModel;
+                const event = {
+                    timestamp: Date.now(),
+                    originalProvider,
+                    fallbackProvider: candidateName,
+                    reason: `${originalProvider} degraded (${health.consecutiveFailures} consecutive failures)`,
+                };
+                this.auditLog.push(event);
+                // Keep audit log bounded
+                if (this.auditLog.length > 1000) {
+                    this.auditLog = this.auditLog.slice(-500);
+                }
+                console.log(`[failover] ${originalProvider} degraded, routing to ${candidateName} (model: ${fallbackModel})`);
+                return {
+                    provider: candidateName,
+                    model: fallbackModel,
+                    failedOver: true,
+                    originalProvider,
+                };
+            }
+        }
+        // All providers degraded (or none have required capabilities) — use the original anyway
+        console.log(`[failover] All providers degraded, attempting ${originalProvider} anyway`);
+        return {
+            provider: originalProvider,
+            model: requestedModel,
+            failedOver: false,
+            originalProvider,
+        };
+    }
+    /**
+     * Record a successful API call — resets consecutive failures and
+     * marks the provider healthy if it was degraded.
+     */
+    recordSuccess(provider) {
+        const health = this.providers.get(provider);
+        if (!health)
+            return;
+        const wasDegraded = health.status === "degraded";
+        health.consecutiveFailures = 0;
+        health.status = "healthy";
+        if (wasDegraded) {
+            console.log(`[failover] ${provider} recovered — marked healthy`);
+        }
+    }
+    /**
+     * Record a failed API call — increments consecutive failures.
+     * If threshold is reached within the failure window, marks degraded.
+     */
+    recordFailure(provider) {
+        const health = this.providers.get(provider);
+        if (!health)
+            return;
+        const now = Date.now();
+        // If last failure was outside the window, reset the counter
+        if (health.lastFailure > 0 && now - health.lastFailure > FAILURE_WINDOW_MS) {
+            health.consecutiveFailures = 0;
+        }
+        health.consecutiveFailures++;
+        health.lastFailure = now;
+        if (health.consecutiveFailures >= DEGRADATION_THRESHOLD &&
+            health.status === "healthy") {
+            health.status = "degraded";
+            health.degradedAt = now;
+            console.log(`[failover] ${provider} marked DEGRADED after ${health.consecutiveFailures} consecutive failures`);
+        }
+    }
+    /**
+     * Start the recovery loop — checks degraded providers every 60s.
+     * Resets them to healthy so the next request can attempt them.
+     * If the attempt fails, recordFailure will re-degrade immediately.
+     */
+    startRecoveryLoop() {
+        if (this.recoveryTimer)
+            return; // already running
+        this.recoveryTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [name, health] of this.providers) {
+                if (health.status === "degraded" &&
+                    now - health.degradedAt >= RECOVERY_CHECK_MS) {
+                    console.log(`[failover] Recovery check: resetting ${name} to healthy for re-probe`);
+                    health.status = "healthy";
+                    health.consecutiveFailures = 0;
+                }
+            }
+        }, RECOVERY_CHECK_MS);
+        // Don't let the recovery timer prevent process exit
+        if (this.recoveryTimer && typeof this.recoveryTimer === "object" && "unref" in this.recoveryTimer) {
+            this.recoveryTimer.unref();
+        }
+    }
+    /**
+     * Stop the recovery loop (for clean shutdown / testing).
+     */
+    stopRecoveryLoop() {
+        if (this.recoveryTimer) {
+            clearInterval(this.recoveryTimer);
+            this.recoveryTimer = null;
+        }
+    }
+    /**
+     * Get current health status of all providers.
+     */
+    getStatus() {
+        return Array.from(this.providers.values()).map((h) => ({ ...h }));
+    }
+    /**
+     * Get the failover audit log.
+     */
+    getAuditLog() {
+        return [...this.auditLog];
+    }
+}
+// ============================================================================
+// SINGLETON — default chain: anthropic → openai → gemini
+// ============================================================================
+export const providerFailover = new ProviderFailover(["anthropic", "openai", "gemini"]);
+providerFailover.startRecoveryLoop();

package/dist/server/lib/rate-limiter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Token-bucket rate limiter — Phase 7.2
+ *
+ * In-memory token buckets supporting per-user, per-IP, per-tool,
+ * and cost-based rate limiting. No external dependencies (Redis etc.)
+ * required — designed for single-server deployment.
+ *
+ * Supplements (does not replace) the existing Supabase RPC rate check.
+ */
+export interface BucketConfig {
+    maxTokens: number;
+    refillRate: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterMs: number;
+    bucket: string;
+}
+export type RateLimitTier = "unauthenticated" | "authenticated" | "serviceRole";
+export declare class RateLimiter {
+    private buckets;
+    private cleanupInterval;
+    private readonly TIERS;
+    private readonly COST_BUDGET;
+    private readonly TOOL_LIMITS;
+    private readonly STALE_MS;
+    constructor();
+    checkRequest(key: string, tier: RateLimitTier): RateLimitResult;
+    checkCostBudget(userId: string, costCents: number): RateLimitResult;
+    checkToolLimit(userId: string, toolName: string): RateLimitResult;
+    getStats(): {
+        totalBuckets: number;
+    };
+    shutdown(): void;
+    private getBucket;
+    private cleanup;
+}
+export declare const rateLimiter: RateLimiter;

package/dist/server/lib/rate-limiter.js

@@ -0,0 +1,147 @@
+/**
+ * Token-bucket rate limiter — Phase 7.2
+ *
+ * In-memory token buckets supporting per-user, per-IP, per-tool,
+ * and cost-based rate limiting. No external dependencies (Redis etc.)
+ * required — designed for single-server deployment.
+ *
+ * Supplements (does not replace) the existing Supabase RPC rate check.
+ */
+import { createLogger } from "./logger.js";
+const log = createLogger("rate-limiter");
+// ============================================================================
+// TOKEN BUCKET
+// ============================================================================
+class TokenBucket {
+    config;
+    tokens;
+    lastRefill;
+    lastAccess;
+    constructor(config) {
+        this.config = config;
+        this.tokens = config.maxTokens;
+        this.lastRefill = Date.now();
+        this.lastAccess = Date.now();
+    }
+    tryConsume(cost = 1) {
+        this.refill();
+        this.lastAccess = Date.now();
+        if (this.tokens >= cost) {
+            this.tokens -= cost;
+            return { allowed: true, remaining: Math.floor(this.tokens), retryAfterMs: 0 };
+        }
+        const refillNeeded = cost - this.tokens;
+        const retryAfterMs = Math.ceil((refillNeeded / this.config.refillRate) * 1000);
+        return { allowed: false, remaining: 0, retryAfterMs };
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        this.tokens = Math.min(this.config.maxTokens, this.tokens + elapsed * this.config.refillRate);
+        this.lastRefill = now;
+    }
+}
+// ============================================================================
+// RATE LIMITER
+// ============================================================================
+export class RateLimiter {
+    buckets = new Map();
+    cleanupInterval;
+    // ---- Tier configs ----
+    TIERS = {
+        unauthenticated: { maxTokens: 5, refillRate: 5 / 60 }, // 5 req/min
+        authenticated: { maxTokens: 100, refillRate: 100 / 60 }, // 100 req/min
+        serviceRole: { maxTokens: 1000, refillRate: 1000 / 60 }, // 1000 req/min
+    };
+    // ---- Cost budget: $10/hour per user (tracked in cents) ----
+    COST_BUDGET = {
+        maxTokens: 1000, // 1000 cents = $10
+        refillRate: 1000 / 3600, // cents per second (~0.278 c/s)
+    };
+    // ---- Per-tool limits ----
+    TOOL_LIMITS = {
+        browser: { maxTokens: 10, refillRate: 10 / 60 }, // 10/min
+        kali_exec: { maxTokens: 20, refillRate: 20 / 60 }, // 20/min
+        kali: { maxTokens: 20, refillRate: 20 / 60 }, // alias
+        local_agent: { maxTokens: 30, refillRate: 30 / 60 }, // 30/min
+    };
+    // Stale bucket threshold (10 minutes)
+    STALE_MS = 600_000;
+    constructor() {
+        // Cleanup stale buckets every 10 minutes
+        this.cleanupInterval = setInterval(() => this.cleanup(), this.STALE_MS);
+        this.cleanupInterval.unref();
+    }
+    // ------------------------------------------------------------------
+    // Public: check per-IP or per-user request rate
+    // ------------------------------------------------------------------
+    checkRequest(key, tier) {
+        const config = this.TIERS[tier];
+        const bucketKey = `req:${tier}:${key}`;
+        const bucket = this.getBucket(bucketKey, config);
+        const result = bucket.tryConsume(1);
+        return { ...result, bucket: bucketKey };
+    }
+    // ------------------------------------------------------------------
+    // Public: check cost budget for a user (cost in cents)
+    // ------------------------------------------------------------------
+    checkCostBudget(userId, costCents) {
+        const bucketKey = `cost:${userId}`;
+        const bucket = this.getBucket(bucketKey, this.COST_BUDGET);
+        const result = bucket.tryConsume(costCents);
+        return { ...result, bucket: bucketKey };
+    }
+    // ------------------------------------------------------------------
+    // Public: check per-tool rate limit
+    // ------------------------------------------------------------------
+    checkToolLimit(userId, toolName) {
+        const config = this.TOOL_LIMITS[toolName];
+        if (!config) {
+            // No specific limit for this tool — allow
+            return { allowed: true, remaining: -1, retryAfterMs: 0, bucket: "none" };
+        }
+        const bucketKey = `tool:${toolName}:${userId}`;
+        const bucket = this.getBucket(bucketKey, config);
+        const result = bucket.tryConsume(1);
+        return { ...result, bucket: bucketKey };
+    }
+    // ------------------------------------------------------------------
+    // Public: get stats for monitoring
+    // ------------------------------------------------------------------
+    getStats() {
+        return { totalBuckets: this.buckets.size };
+    }
+    // ------------------------------------------------------------------
+    // Public: teardown
+    // ------------------------------------------------------------------
+    shutdown() {
+        clearInterval(this.cleanupInterval);
+        this.buckets.clear();
+    }
+    // ------------------------------------------------------------------
+    // Private helpers
+    // ------------------------------------------------------------------
+    getBucket(key, config) {
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = new TokenBucket(config);
+            this.buckets.set(key, bucket);
+        }
+        return bucket;
+    }
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, bucket] of this.buckets) {
+            if (now - bucket.lastAccess > this.STALE_MS) {
+                this.buckets.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            log.debug({ removed, remaining: this.buckets.size }, "rate-limiter cleanup");
+        }
+    }
+}
+// Singleton instance
+export const rateLimiter = new RateLimiter();