@relayplane/proxy 1.8.10 → 1.8.11

package/dist/recovery.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Adaptive Provider Recovery — Phase 1: Local Recovery
+ *
+ * Detects provider errors, applies recovery strategies with exponential backoff,
+ * extracts recovery patterns from successful retries, and applies them preemptively.
+ *
+ * @packageDocumentation
+ */
+import { type Logger } from './logger.js';
+/** Categories of recovery patterns the system can detect and apply */
+export type RecoveryPatternType = 'auth-header' | 'model-rename' | 'timeout-tune' | 'provider-fallback';
+/** Context captured when a provider request fails */
+export interface FailureContext {
+    provider: string;
+    model: string;
+    authMethod: string;
+    errorCode: number;
+    errorMessage: string;
+    errorType: string;
+    tokenPrefix?: string;
+    timestamp: number;
+    requestHeaders: Record<string, string>;
+    estimatedTokens?: number;
+    timeoutMs?: number;
+}
+/** A discovered recovery pattern */
+export interface RecoveryPattern {
+    id: string;
+    type: RecoveryPatternType;
+    provider: string;
+    trigger: {
+        errorCode: number;
+        errorType?: string;
+        tokenPrefix?: string;
+        model?: string;
+        minTokens?: number;
+    };
+    fix: {
+        authHeader?: string;
+        model?: string;
+        timeoutMs?: number;
+        provider?: string;
+    };
+    confidence: number;
+    successCount: number;
+    failureCount: number;
+    firstSeen: string;
+    lastSeen: string;
+    lastApplied?: string;
+}
+/** Result of a recovery attempt */
+export interface RecoveryResult {
+    recovered: boolean;
+    strategy: string;
+    pattern?: RecoveryPattern;
+    response?: ProviderResponse;
+    attempts: number;
+    totalLatencyMs: number;
+}
+/** Provider response shape (simplified) */
+export interface ProviderResponse {
+    success: boolean;
+    status?: number;
+    data?: unknown;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    ttft_ms?: number;
+    error?: {
+        code: string;
+        message: string;
+        status: number;
+        retryable: boolean;
+        raw?: unknown;
+    };
+}
+/** A recovery event logged for observability */
+export interface RecoveryEvent {
+    id: string;
+    timestamp: string;
+    provider: string;
+    model: string;
+    originalError: {
+        code: number;
+        type: string;
+        message: string;
+    };
+    strategy: string;
+    recovered: boolean;
+    attempts: number;
+    latencyMs: number;
+    patternId?: string;
+    delta?: Record<string, unknown>;
+}
+/** Function that forwards a request to a provider */
+export type ForwardFn = (provider: string, request: Record<string, unknown>, config: {
+    apiKey: string;
+    baseUrl?: string;
+}, runId: string, overrides?: RequestOverrides) => Promise<ProviderResponse>;
+/** Overrides that recovery strategies can apply to a request */
+export interface RequestOverrides {
+    authHeader?: string;
+    model?: string;
+    timeoutMs?: number;
+}
+export interface RecoveryConfig {
+    /** Enable/disable recovery (default: true) */
+    enabled?: boolean;
+    /** Maximum retry attempts per failure (default: 2) */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms (default: 500) */
+    baseDelayMs?: number;
+    /** Maximum backoff delay in ms (default: 5000) */
+    maxDelayMs?: number;
+    /** Minimum confidence for preemptive pattern application (default: 0.8) */
+    minPreemptiveConfidence?: number;
+    /** Maximum stored patterns (default: 100) */
+    maxPatterns?: number;
+    /** Pattern expiry in days (default: 30) */
+    patternExpiryDays?: number;
+    /** Logger */
+    logger?: Logger;
+}
+/**
+ * In-memory store for recovery patterns.
+ * Phase 1 uses in-memory; Phase 2 could use SQLite.
+ */
+export declare class RecoveryPatternStore {
+    private patterns;
+    private readonly maxPatterns;
+    private readonly expiryDays;
+    constructor(maxPatterns?: number, expiryDays?: number);
+    /** Get all patterns */
+    getAll(): RecoveryPattern[];
+    /** Find patterns matching a failure context */
+    findMatching(ctx: FailureContext): RecoveryPattern[];
+    /** Find preemptive patterns for a request (before any failure) */
+    findPreemptive(provider: string, model: string, tokenPrefix?: string): RecoveryPattern[];
+    /** Store or update a pattern */
+    upsert(pattern: RecoveryPattern): void;
+    /** Record a successful application of a pattern */
+    recordSuccess(patternId: string): void;
+    /** Record a failed application of a pattern */
+    recordFailure(patternId: string): void;
+    /** Get store stats */
+    stats(): {
+        total: number;
+        highConfidence: number;
+        avgConfidence: number;
+    };
+    private pruneExpired;
+}
+/**
+ * Observes provider failures and determines if they are recovery-eligible.
+ */
+export declare class FailureObserver {
+    private readonly logger;
+    private readonly events;
+    private readonly maxEvents;
+    constructor(logger?: Logger);
+    /** Determine if a failure is eligible for recovery attempt */
+    isRecoverable(response: ProviderResponse): boolean;
+    /** Build failure context from a failed request */
+    buildContext(provider: string, model: string, request: Record<string, unknown>, config: {
+        apiKey: string;
+        baseUrl?: string;
+    }, response: ProviderResponse, overrides?: RequestOverrides): FailureContext;
+    /** Log a recovery event */
+    logEvent(event: RecoveryEvent): void;
+    /** Get recent recovery events */
+    getRecentEvents(limit?: number): RecoveryEvent[];
+    /** Get recovery stats */
+    getStats(): {
+        total: number;
+        recovered: number;
+        failed: number;
+        recoveryRate: number;
+    };
+}
+/**
+ * Applies stored recovery patterns preemptively before forwarding requests.
+ */
+export declare class PatternApplicator {
+    private readonly store;
+    private readonly minConfidence;
+    private readonly logger;
+    private preemptiveHits;
+    private preemptiveMisses;
+    constructor(store: RecoveryPatternStore, minConfidence?: number, logger?: Logger);
+    /**
+     * Check for preemptive patterns and return overrides to apply.
+     * Called before forwarding a request.
+     */
+    getPreemptiveOverrides(provider: string, model: string, apiKey?: string): RequestOverrides | null;
+    /** Record that a preemptive application worked */
+    recordPreemptiveSuccess(provider: string, model: string): void;
+    /** Record that a preemptive application failed */
+    recordPreemptiveFailure(provider: string, model: string): void;
+    /** Get preemptive application stats */
+    getStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+}
+/**
+ * Main recovery engine that orchestrates failure observation,
+ * recovery strategies, pattern extraction, and preemptive application.
+ */
+export declare class RecoveryEngine {
+    readonly observer: FailureObserver;
+    readonly store: RecoveryPatternStore;
+    readonly applicator: PatternApplicator;
+    private readonly config;
+    private readonly logger;
+    constructor(config?: RecoveryConfig);
+    /** Check if recovery is enabled */
+    get enabled(): boolean;
+    /**
+     * Get preemptive overrides to apply before forwarding.
+     * Called by the request pipeline before forwardToProvider.
+     */
+    getPreemptiveOverrides(provider: string, model: string, apiKey?: string): RequestOverrides | null;
+    /**
+     * Attempt to recover from a provider failure.
+     * Tries applicable strategies with exponential backoff.
+     *
+     * @returns RecoveryResult with the outcome
+     */
+    attemptRecovery(provider: string, model: string, request: Record<string, unknown>, providerConfig: {
+        apiKey: string;
+        baseUrl?: string;
+    }, runId: string, failedResponse: ProviderResponse, forwardFn: ForwardFn): Promise<RecoveryResult>;
+    /**
+     * Get recovery dashboard data
+     */
+    getDashboardData(): {
+        enabled: boolean;
+        patterns: RecoveryPattern[];
+        patternStats: {
+            total: number;
+            highConfidence: number;
+            avgConfidence: number;
+        };
+        recoveryStats: {
+            total: number;
+            recovered: number;
+            failed: number;
+            recoveryRate: number;
+        };
+        preemptiveStats: {
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        recentEvents: RecoveryEvent[];
+    };
+    private logRecoveryEvent;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

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