profclaw 0.0.1-beta.1

package/dist/chat/failover/error.js

@@ -0,0 +1,412 @@
+/**
+ * Failover Error System
+ *
+ * Error classification and FailoverError class for provider failover.
+ * Based on OpenClaw's sophisticated error handling patterns.
+ */
+// Error Detection Patterns
+const TIMEOUT_HINT_RE = /timeout|timed out|deadline exceeded|context deadline exceeded/i;
+const ABORT_TIMEOUT_RE = /request was aborted|request aborted/i;
+/**
+ * Error patterns for classifying errors by type.
+ * These patterns are used to determine if an error is recoverable via fallback.
+ */
+const ERROR_PATTERNS = {
+    rateLimit: [
+        /rate[_ ]limit/i,
+        /too many requests/i,
+        /429/,
+        /exceeded your current quota/i,
+        /resource has been exhausted/i,
+        /quota exceeded/i,
+        /resource_exhausted/i,
+        /usage limit/i,
+        /overloaded/i,
+        /overloaded_error/i,
+        /capacity/i,
+    ],
+    timeout: [
+        /timeout/i,
+        /timed out/i,
+        /deadline exceeded/i,
+        /context deadline exceeded/i,
+        /ETIMEDOUT/,
+        /ESOCKETTIMEDOUT/,
+        /ECONNRESET/,
+        /ECONNABORTED/,
+    ],
+    billing: [
+        /402/,
+        /payment required/i,
+        /insufficient credits/i,
+        /credit balance/i,
+        /plans & billing/i,
+        /billing/i,
+        /upgrade.*plan/i,
+    ],
+    auth: [
+        /invalid[_ ]?api[_ ]?key/i,
+        /incorrect api key/i,
+        /invalid token/i,
+        /authentication/i,
+        /re-authenticate/i,
+        /oauth token refresh failed/i,
+        /unauthorized/i,
+        /forbidden/i,
+        /access denied/i,
+        /expired/i,
+        /token has expired/i,
+        /401/,
+        /403/,
+        /no credentials found/i,
+        /no api key found/i,
+        /api.*key.*invalid/i,
+    ],
+    format: [
+        /string should match pattern/i,
+        /tool_use\.id/i,
+        /tool_use_id/i,
+        /invalid request format/i,
+        /invalid_request_error/i,
+        /malformed/i,
+    ],
+    deployment: [
+        /deployment.*does not exist/i,
+        /deployment.*not found/i,
+        /model.*not found/i,
+        /model.*does not exist/i,
+        /resource.*not found/i,
+        /endpoint.*not found/i,
+    ],
+    connection: [
+        /ECONNREFUSED/,
+        /ENOTFOUND/,
+        /EHOSTUNREACH/,
+        /endpoint.*not.*reachable/i,
+        /503.*service.*unavailable/i,
+        /502.*bad.*gateway/i,
+        /504.*gateway.*timeout/i,
+        /network.*error/i,
+        /fetch failed/i,
+    ],
+};
+// FailoverError Class
+/**
+ * Error class that includes failover metadata.
+ * Used to track and propagate error context through the fallback chain.
+ */
+export class FailoverError extends Error {
+    reason;
+    provider;
+    model;
+    status;
+    code;
+    constructor(message, params) {
+        super(message, { cause: params.cause });
+        this.name = 'FailoverError';
+        this.reason = params.reason;
+        this.provider = params.provider;
+        this.model = params.model;
+        this.status = params.status;
+        this.code = params.code;
+    }
+}
+// Error Classification Functions
+/**
+ * Check if an error is a FailoverError
+ */
+export function isFailoverError(err) {
+    return err instanceof FailoverError;
+}
+/**
+ * Resolve HTTP status code from failover reason
+ */
+export function resolveFailoverStatus(reason) {
+    switch (reason) {
+        case 'billing':
+            return 402;
+        case 'rate_limit':
+            return 429;
+        case 'auth':
+            return 401;
+        case 'timeout':
+            return 408;
+        case 'format':
+            return 400;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Extract status code from an error object
+ */
+function getStatusCode(err) {
+    if (!err || typeof err !== 'object') {
+        return undefined;
+    }
+    const candidate = err.status ??
+        err.statusCode;
+    if (typeof candidate === 'number') {
+        return candidate;
+    }
+    if (typeof candidate === 'string' && /^\d+$/.test(candidate)) {
+        return Number(candidate);
+    }
+    return undefined;
+}
+/**
+ * Extract error name from an error object
+ */
+function getErrorName(err) {
+    if (!err || typeof err !== 'object') {
+        return '';
+    }
+    return 'name' in err ? String(err.name) : '';
+}
+/**
+ * Extract error code from an error object
+ */
+function getErrorCode(err) {
+    if (!err || typeof err !== 'object') {
+        return undefined;
+    }
+    const candidate = err.code;
+    if (typeof candidate !== 'string') {
+        return undefined;
+    }
+    const trimmed = candidate.trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * Extract error message from any value
+ */
+function getErrorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (typeof err === 'number' || typeof err === 'boolean' || typeof err === 'bigint') {
+        return String(err);
+    }
+    if (typeof err === 'symbol') {
+        return err.description ?? '';
+    }
+    if (err && typeof err === 'object') {
+        const message = err.message;
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    return '';
+}
+/**
+ * Check if an error has timeout indicators
+ */
+function hasTimeoutHint(err) {
+    if (!err) {
+        return false;
+    }
+    if (getErrorName(err) === 'TimeoutError') {
+        return true;
+    }
+    const message = getErrorMessage(err);
+    return Boolean(message && TIMEOUT_HINT_RE.test(message));
+}
+/**
+ * Check if an error is a timeout error
+ */
+export function isTimeoutError(err) {
+    if (hasTimeoutHint(err)) {
+        return true;
+    }
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    if (getErrorName(err) !== 'AbortError') {
+        return false;
+    }
+    const message = getErrorMessage(err);
+    if (message && ABORT_TIMEOUT_RE.test(message)) {
+        return true;
+    }
+    const cause = 'cause' in err ? err.cause : undefined;
+    const reason = 'reason' in err ? err.reason : undefined;
+    return hasTimeoutHint(cause) || hasTimeoutHint(reason);
+}
+/**
+ * Check if an error matches any patterns in a list
+ */
+function matchesPatterns(message, patterns) {
+    if (!message)
+        return false;
+    return patterns.some((pattern) => pattern.test(message));
+}
+/**
+ * Classify an error message into a failover reason
+ */
+export function classifyFailoverReason(raw) {
+    if (!raw)
+        return null;
+    // Check patterns in order of specificity
+    if (matchesPatterns(raw, ERROR_PATTERNS.rateLimit)) {
+        return 'rate_limit';
+    }
+    if (matchesPatterns(raw, ERROR_PATTERNS.format)) {
+        return 'format';
+    }
+    if (matchesPatterns(raw, ERROR_PATTERNS.billing)) {
+        return 'billing';
+    }
+    if (matchesPatterns(raw, ERROR_PATTERNS.timeout)) {
+        return 'timeout';
+    }
+    if (matchesPatterns(raw, ERROR_PATTERNS.auth)) {
+        return 'auth';
+    }
+    // Deployment and connection errors warrant fallback but don't have a specific reason
+    if (matchesPatterns(raw, ERROR_PATTERNS.deployment)) {
+        return 'unknown';
+    }
+    if (matchesPatterns(raw, ERROR_PATTERNS.connection)) {
+        return 'unknown';
+    }
+    return null;
+}
+/**
+ * Resolve failover reason from an error object
+ */
+export function resolveFailoverReasonFromError(err) {
+    if (isFailoverError(err)) {
+        return err.reason;
+    }
+    // Check status code first
+    const status = getStatusCode(err);
+    if (status === 402) {
+        return 'billing';
+    }
+    if (status === 429) {
+        return 'rate_limit';
+    }
+    if (status === 401 || status === 403) {
+        return 'auth';
+    }
+    if (status === 408) {
+        return 'timeout';
+    }
+    // Check error code
+    const code = (getErrorCode(err) ?? '').toUpperCase();
+    if (['ETIMEDOUT', 'ESOCKETTIMEDOUT', 'ECONNRESET', 'ECONNABORTED'].includes(code)) {
+        return 'timeout';
+    }
+    if (['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH'].includes(code)) {
+        return 'unknown';
+    }
+    // Check for timeout patterns
+    if (isTimeoutError(err)) {
+        return 'timeout';
+    }
+    // Finally, classify by message content
+    const message = getErrorMessage(err);
+    if (!message) {
+        return null;
+    }
+    return classifyFailoverReason(message);
+}
+/**
+ * Describe a failover error for logging/display
+ */
+export function describeFailoverError(err) {
+    if (isFailoverError(err)) {
+        return {
+            message: err.message,
+            reason: err.reason,
+            status: err.status,
+            code: err.code,
+        };
+    }
+    const message = getErrorMessage(err) || String(err);
+    return {
+        message,
+        reason: resolveFailoverReasonFromError(err) ?? undefined,
+        status: getStatusCode(err),
+        code: getErrorCode(err),
+    };
+}
+/**
+ * Convert any error into a FailoverError if it matches failover criteria.
+ * Returns null if the error doesn't warrant a failover attempt.
+ */
+export function coerceToFailoverError(err, context) {
+    if (isFailoverError(err)) {
+        return err;
+    }
+    const reason = resolveFailoverReasonFromError(err);
+    if (!reason) {
+        return null;
+    }
+    const message = getErrorMessage(err) || String(err);
+    const status = getStatusCode(err) ?? resolveFailoverStatus(reason);
+    const code = getErrorCode(err);
+    return new FailoverError(message, {
+        reason,
+        provider: context?.provider,
+        model: context?.model,
+        status,
+        code,
+        cause: err instanceof Error ? err : undefined,
+    });
+}
+/**
+ * Check if an error is an AbortError (user cancellation, not timeout)
+ */
+function isAbortError(err) {
+    if (!err || typeof err !== 'object') {
+        return false;
+    }
+    if (isFailoverError(err)) {
+        return false;
+    }
+    const name = 'name' in err ? String(err.name) : '';
+    return name === 'AbortError';
+}
+/**
+ * Check if an error should be rethrown without attempting fallback.
+ * User-initiated aborts should not trigger fallback.
+ */
+export function shouldRethrowWithoutFallback(err) {
+    return isAbortError(err) && !isTimeoutError(err);
+}
+/**
+ * Get a user-friendly error message based on the error and provider
+ */
+export function getUserFriendlyErrorMessage(err, provider) {
+    const reason = resolveFailoverReasonFromError(err);
+    const message = getErrorMessage(err) || 'Unknown error';
+    switch (reason) {
+        case 'auth':
+            return `Invalid API key for ${provider}. Please update your API key in Settings > Integrations.`;
+        case 'rate_limit':
+            return `Rate limit exceeded for ${provider}. Please try again later or switch providers.`;
+        case 'billing':
+            return `Billing issue with ${provider}. Please check your account balance or upgrade your plan.`;
+        case 'timeout':
+            return `Request to ${provider} timed out. The server may be overloaded. Try again or switch providers.`;
+        case 'format':
+            return `Request format error with ${provider}. This may be a compatibility issue.`;
+        case 'unknown':
+            // Check for specific deployment/connection patterns
+            if (matchesPatterns(message, ERROR_PATTERNS.deployment)) {
+                return `Model or deployment not found on ${provider}. Please check your configuration in Settings > Integrations.`;
+            }
+            if (matchesPatterns(message, ERROR_PATTERNS.connection)) {
+                return `Cannot connect to ${provider}. Check your network or the provider's status.`;
+            }
+            return `Connection issue with ${provider}: ${message.substring(0, 100)}`;
+        default:
+            // Return truncated original message
+            return message.length > 150 ? `${message.substring(0, 150)}...` : message;
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/chat/failover/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Provider Failover System
+ *
+ * Exports for the comprehensive provider failover system.
+ * Based on OpenClaw's sophisticated error handling and fallback patterns.
+ */
+export type { FailoverReason, FallbackAttempt, ModelFallbackResult, ProviderCooldown } from './types.js';
+export { FailoverError, isFailoverError, resolveFailoverStatus, isTimeoutError, classifyFailoverReason, resolveFailoverReasonFromError, describeFailoverError, coerceToFailoverError, shouldRethrowWithoutFallback, getUserFriendlyErrorMessage, } from './error.js';
+export { runWithModelFallback, runWithFallback, buildFallbackCandidates, isProviderInCooldown, getProviderCooldownRemaining, setProviderCooldown, clearProviderCooldown, getProvidersInCooldown, type ModelResolver, } from './model-fallback.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chat/failover/index.js

@@ -0,0 +1,11 @@
+/**
+ * Provider Failover System
+ *
+ * Exports for the comprehensive provider failover system.
+ * Based on OpenClaw's sophisticated error handling and fallback patterns.
+ */
+// Error utilities
+export { FailoverError, isFailoverError, resolveFailoverStatus, isTimeoutError, classifyFailoverReason, resolveFailoverReasonFromError, describeFailoverError, coerceToFailoverError, shouldRethrowWithoutFallback, getUserFriendlyErrorMessage, } from './error.js';
+// Model fallback
+export { runWithModelFallback, runWithFallback, buildFallbackCandidates, isProviderInCooldown, getProviderCooldownRemaining, setProviderCooldown, clearProviderCooldown, getProvidersInCooldown, } from './model-fallback.js';
+//# sourceMappingURL=index.js.map

package/dist/chat/failover/model-fallback.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Model Fallback System
+ *
+ * Provides automatic failover between AI providers when requests fail.
+ * Based on OpenClaw's sophisticated model fallback patterns.
+ */
+import type { ProviderType } from '../../providers/index.js';
+import type { ModelFallbackResult, ProviderCooldown, FailoverReason } from './types.js';
+import { FailoverError, getUserFriendlyErrorMessage } from './error.js';
+/**
+ * Check if a provider is currently in cooldown
+ */
+export declare function isProviderInCooldown(provider: string): boolean;
+/**
+ * Get the remaining cooldown time for a provider
+ */
+export declare function getProviderCooldownRemaining(provider: string): number;
+/**
+ * Put a provider into cooldown
+ */
+export declare function setProviderCooldown(provider: string, reason: FailoverReason, error: string): void;
+/**
+ * Clear cooldown for a provider (e.g., after successful request)
+ */
+export declare function clearProviderCooldown(provider: string): void;
+/**
+ * Get all providers currently in cooldown
+ */
+export declare function getProvidersInCooldown(): ProviderCooldown[];
+/**
+ * Model candidate for fallback
+ */
+interface ModelCandidate {
+    provider: ProviderType;
+    model: string;
+}
+/**
+ * Model resolver function type
+ * Returns the configured model for a provider, or undefined if not configured
+ */
+export type ModelResolver = (provider: ProviderType) => string | undefined;
+/**
+ * Build the list of model candidates for fallback
+ */
+export declare function buildFallbackCandidates(params: {
+    primaryProvider: ProviderType;
+    primaryModel: string;
+    configuredProviders: ProviderType[];
+    fallbackOverrides?: string[];
+    /** Optional resolver to get provider-specific configured models */
+    modelResolver?: ModelResolver;
+}): ModelCandidate[];
+/**
+ * Run an operation with automatic model fallback.
+ * Tries the primary provider first, then falls back to other providers on failure.
+ *
+ * @param params.primaryProvider - The primary provider to try first
+ * @param params.primaryModel - The primary model to try first
+ * @param params.configuredProviders - List of all configured/available providers
+ * @param params.fallbackOverrides - Optional explicit fallback list (e.g., ["openai/gpt-4", "anthropic/claude-3"])
+ * @param params.modelResolver - Optional resolver to get provider-specific configured models
+ * @param params.run - The operation to run with provider and model
+ * @param params.onError - Optional callback when an attempt fails
+ * @returns Result with the successful provider/model and attempt history
+ */
+export declare function runWithModelFallback<T>(params: {
+    primaryProvider: ProviderType;
+    primaryModel: string;
+    configuredProviders: ProviderType[];
+    fallbackOverrides?: string[];
+    /** Resolver to get the configured model for a provider (e.g., Azure deployment name) */
+    modelResolver?: ModelResolver;
+    run: (provider: ProviderType, model: string) => Promise<T>;
+    onError?: (attempt: {
+        provider: ProviderType;
+        model: string;
+        error: unknown;
+        attempt: number;
+        total: number;
+    }) => void | Promise<void>;
+}): Promise<ModelFallbackResult<T>>;
+/**
+ * Convenience wrapper for simple fallback scenarios
+ */
+export declare function runWithFallback<T>(params: {
+    primary: {
+        provider: ProviderType;
+        model: string;
+    };
+    fallbacks: Array<{
+        provider: ProviderType;
+        model: string;
+    }>;
+    run: (provider: ProviderType, model: string) => Promise<T>;
+}): Promise<ModelFallbackResult<T>>;
+export { FailoverError, getUserFriendlyErrorMessage };
+//# sourceMappingURL=model-fallback.d.ts.map