profclaw 0.0.1-beta.1

package/dist/chat/failover/model-fallback.js

@@ -0,0 +1,328 @@
+/**
+ * Model Fallback System
+ *
+ * Provides automatic failover between AI providers when requests fail.
+ * Based on OpenClaw's sophisticated model fallback patterns.
+ */
+import { logger } from '../../utils/logger.js';
+import { FailoverError, coerceToFailoverError, describeFailoverError, isFailoverError, shouldRethrowWithoutFallback, getUserFriendlyErrorMessage, } from './error.js';
+// Cooldown Management
+/**
+ * Cooldown durations by failure reason (in milliseconds)
+ */
+const COOLDOWN_DURATIONS = {
+    rate_limit: 60000, // 1 minute for rate limits
+    billing: 300000, // 5 minutes for billing issues
+    auth: 300000, // 5 minutes for auth issues (need user action)
+    timeout: 30000, // 30 seconds for timeouts
+    format: 0, // No cooldown for format errors (may be request-specific)
+    unknown: 60000, // 1 minute for unknown errors
+};
+/**
+ * In-memory provider cooldown tracking
+ * Maps provider name to cooldown entry
+ */
+const providerCooldowns = new Map();
+/**
+ * Check if a provider is currently in cooldown
+ */
+export function isProviderInCooldown(provider) {
+    const cooldown = providerCooldowns.get(provider);
+    if (!cooldown)
+        return false;
+    if (Date.now() >= cooldown.cooldownUntil) {
+        // Cooldown expired, remove it
+        providerCooldowns.delete(provider);
+        return false;
+    }
+    return true;
+}
+/**
+ * Get the remaining cooldown time for a provider
+ */
+export function getProviderCooldownRemaining(provider) {
+    const cooldown = providerCooldowns.get(provider);
+    if (!cooldown)
+        return 0;
+    const remaining = cooldown.cooldownUntil - Date.now();
+    return remaining > 0 ? remaining : 0;
+}
+/**
+ * Put a provider into cooldown
+ */
+export function setProviderCooldown(provider, reason, error) {
+    const duration = COOLDOWN_DURATIONS[reason] || COOLDOWN_DURATIONS.unknown;
+    if (duration === 0)
+        return;
+    providerCooldowns.set(provider, {
+        provider,
+        reason,
+        cooldownUntil: Date.now() + duration,
+        lastError: error,
+    });
+    logger.info('[ModelFallback] Provider put in cooldown', {
+        provider,
+        reason,
+        durationMs: duration,
+        error: error.substring(0, 100),
+    });
+}
+/**
+ * Clear cooldown for a provider (e.g., after successful request)
+ */
+export function clearProviderCooldown(provider) {
+    providerCooldowns.delete(provider);
+}
+/**
+ * Get all providers currently in cooldown
+ */
+export function getProvidersInCooldown() {
+    const now = Date.now();
+    const result = [];
+    for (const [provider, cooldown] of providerCooldowns.entries()) {
+        if (now < cooldown.cooldownUntil) {
+            result.push(cooldown);
+        }
+        else {
+            providerCooldowns.delete(provider);
+        }
+    }
+    return result;
+}
+/**
+ * Default models for each provider
+ */
+const DEFAULT_MODELS = {
+    anthropic: 'claude-sonnet-4-5-20251014',
+    openai: 'gpt-4.1',
+    azure: 'default', // Uses configured deployment - not hardcoded
+    google: 'gemini-2.5-pro-preview-05-06',
+    groq: 'llama-3.3-70b-versatile',
+    ollama: 'llama3.2',
+    openrouter: 'anthropic/claude-3.5-sonnet',
+    xai: 'grok-2',
+    mistral: 'mistral-large-latest',
+    cohere: 'command-r-plus',
+    perplexity: 'llama-3.1-sonar-huge-128k-online',
+    deepseek: 'deepseek-chat',
+    together: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+    cerebras: 'llama3.1-70b',
+    fireworks: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
+    copilot: 'gpt-4o',
+    bedrock: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+    zhipu: 'glm-4-plus',
+    moonshot: 'moonshot-v1-32k',
+    qwen: 'qwen-max',
+    replicate: 'meta/llama-3.1-405b-instruct',
+    'github-models': 'gpt-4o',
+};
+/**
+ * Preferred fallback order for providers
+ */
+const FALLBACK_PROVIDER_ORDER = [
+    'anthropic',
+    'openai',
+    'google',
+    'azure',
+    'bedrock',
+    'groq',
+    'openrouter',
+    'mistral',
+    'deepseek',
+    'together',
+    'xai',
+    'zhipu',
+    'moonshot',
+    'qwen',
+    'cohere',
+    'perplexity',
+    'fireworks',
+    'cerebras',
+    'replicate',
+    'github-models',
+    'ollama',
+    'copilot',
+];
+/**
+ * Build the list of model candidates for fallback
+ */
+export function buildFallbackCandidates(params) {
+    const seen = new Set();
+    const candidates = [];
+    const addCandidate = (provider, model) => {
+        const key = `${provider}/${model}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        candidates.push({ provider, model });
+    };
+    // 1. Add primary model first
+    addCandidate(params.primaryProvider, params.primaryModel);
+    // 2. If fallback overrides are provided, use those
+    if (params.fallbackOverrides && params.fallbackOverrides.length > 0) {
+        for (const fallback of params.fallbackOverrides) {
+            const parts = fallback.split('/');
+            if (parts.length === 2) {
+                const [provider, model] = parts;
+                if (params.configuredProviders.includes(provider)) {
+                    addCandidate(provider, model);
+                }
+            }
+        }
+        return candidates;
+    }
+    // 3. Add other configured providers in preferred order
+    for (const provider of FALLBACK_PROVIDER_ORDER) {
+        if (provider === params.primaryProvider)
+            continue;
+        if (!params.configuredProviders.includes(provider))
+            continue;
+        // Use the resolver if provided (gets user's configured model for provider)
+        // Otherwise fall back to hardcoded defaults
+        const model = params.modelResolver?.(provider) || DEFAULT_MODELS[provider] || 'default';
+        addCandidate(provider, model);
+    }
+    return candidates;
+}
+// Run With Model Fallback
+/**
+ * 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 async function runWithModelFallback(params) {
+    const candidates = buildFallbackCandidates({
+        primaryProvider: params.primaryProvider,
+        primaryModel: params.primaryModel,
+        configuredProviders: params.configuredProviders,
+        fallbackOverrides: params.fallbackOverrides,
+        modelResolver: params.modelResolver,
+    });
+    const attempts = [];
+    let lastError;
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        // Check if provider is in cooldown
+        if (isProviderInCooldown(candidate.provider)) {
+            const remaining = getProviderCooldownRemaining(candidate.provider);
+            attempts.push({
+                provider: candidate.provider,
+                model: candidate.model,
+                error: `Provider ${candidate.provider} is in cooldown (${Math.ceil(remaining / 1000)}s remaining)`,
+                reason: 'rate_limit',
+                skippedDueToCooldown: true,
+            });
+            continue;
+        }
+        try {
+            logger.debug('[ModelFallback] Trying candidate', {
+                provider: candidate.provider,
+                model: candidate.model,
+                attempt: i + 1,
+                total: candidates.length,
+            });
+            const result = await params.run(candidate.provider, candidate.model);
+            // Success! Clear any cooldown for this provider
+            clearProviderCooldown(candidate.provider);
+            return {
+                result,
+                provider: candidate.provider,
+                model: candidate.model,
+                attempts,
+            };
+        }
+        catch (err) {
+            // Check if this is a user abort that shouldn't trigger fallback
+            if (shouldRethrowWithoutFallback(err)) {
+                throw err;
+            }
+            // Try to classify the error
+            const normalized = coerceToFailoverError(err, {
+                provider: candidate.provider,
+                model: candidate.model,
+            });
+            // If we couldn't classify it as a failover error, it may be a code bug - rethrow
+            if (!normalized && !isFailoverError(err)) {
+                // Check if the error at least looks like a provider error
+                const message = err instanceof Error ? err.message : String(err);
+                const looksLikeProviderError = message.includes('API') ||
+                    message.includes('request') ||
+                    message.includes('connection') ||
+                    message.includes('timeout') ||
+                    message.includes('error');
+                if (!looksLikeProviderError) {
+                    throw err;
+                }
+            }
+            lastError = normalized || err;
+            const described = describeFailoverError(lastError);
+            // Record the attempt
+            attempts.push({
+                provider: candidate.provider,
+                model: candidate.model,
+                error: described.message,
+                reason: described.reason,
+                status: described.status,
+                code: described.code,
+            });
+            // Put provider in cooldown if appropriate
+            if (described.reason) {
+                setProviderCooldown(candidate.provider, described.reason, described.message);
+            }
+            // Notify about the error
+            await params.onError?.({
+                provider: candidate.provider,
+                model: candidate.model,
+                error: lastError,
+                attempt: i + 1,
+                total: candidates.length,
+            });
+            logger.warn('[ModelFallback] Attempt failed', {
+                provider: candidate.provider,
+                model: candidate.model,
+                error: described.message,
+                reason: described.reason,
+                attempt: i + 1,
+                total: candidates.length,
+            });
+        }
+    }
+    // All attempts failed
+    if (attempts.length <= 1 && lastError) {
+        // Single attempt, throw the original error
+        throw lastError;
+    }
+    // Multiple attempts, create a summary error
+    const summary = attempts.length > 0
+        ? attempts
+            .map((attempt) => `${attempt.provider}/${attempt.model}: ${attempt.error}${attempt.reason ? ` (${attempt.reason})` : ''}`)
+            .join(' | ')
+        : 'unknown';
+    throw new FailoverError(`All ${attempts.length} providers failed: ${summary}`, {
+        reason: 'unknown',
+        cause: lastError instanceof Error ? lastError : undefined,
+    });
+}
+/**
+ * Convenience wrapper for simple fallback scenarios
+ */
+export async function runWithFallback(params) {
+    const allProviders = [params.primary, ...params.fallbacks].map((p) => p.provider);
+    return runWithModelFallback({
+        primaryProvider: params.primary.provider,
+        primaryModel: params.primary.model,
+        configuredProviders: [...new Set(allProviders)],
+        fallbackOverrides: params.fallbacks.map((f) => `${f.provider}/${f.model}`),
+        run: params.run,
+    });
+}
+export { FailoverError, getUserFriendlyErrorMessage };
+//# sourceMappingURL=model-fallback.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * Failover Types
+ *
+ * Type definitions for the provider failover system.
+ * Based on OpenClaw's sophisticated error handling patterns.
+ */
+/**
+ * Reasons why a provider request might fail that warrant trying a fallback.
+ * - auth: Invalid API key, expired token, authentication failure
+ * - format: Invalid request format, malformed parameters
+ * - rate_limit: Rate limited or quota exceeded (includes overloaded)
+ * - billing: Payment required, insufficient credits
+ * - timeout: Request timeout, connection timeout
+ * - unknown: Unknown error that still warrants fallback
+ */
+export type FailoverReason = 'auth' | 'format' | 'rate_limit' | 'billing' | 'timeout' | 'unknown';
+/**
+ * Record of a fallback attempt
+ */
+export interface FallbackAttempt {
+    provider: string;
+    model: string;
+    error: string;
+    reason?: FailoverReason;
+    status?: number;
+    code?: string;
+    skippedDueToCooldown?: boolean;
+}
+/**
+ * Result of running with model fallback
+ */
+export interface ModelFallbackResult<T> {
+    result: T;
+    provider: string;
+    model: string;
+    attempts: FallbackAttempt[];
+}
+/**
+ * Provider cooldown entry
+ */
+export interface ProviderCooldown {
+    provider: string;
+    reason: FailoverReason;
+    cooldownUntil: number;
+    lastError: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/failover/types.js

@@ -0,0 +1,8 @@
+/**
+ * Failover Types
+ *
+ * Type definitions for the provider failover system.
+ * Based on OpenClaw's sophisticated error handling patterns.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/chat/format/chunk.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Text Chunking Utility
+ *
+ * Splits long text into chunks that fit within per-platform message limits.
+ * Handles two splitting strategies:
+ * - length: split at word boundaries up to the character limit
+ * - newline: split at paragraph/newline boundaries
+ *
+ * Code blocks (```) are always kept intact - never split mid-block.
+ */
+import type { ChatProviderId } from '../providers/types.js';
+/** How to determine split points when chunking */
+export type ChunkMode = 'length' | 'newline';
+export interface ChunkOptions {
+    /** Splitting strategy. Defaults to 'length'. */
+    mode?: ChunkMode;
+    /**
+     * Override the platform character limit.
+     * Use 0 for unlimited (returns single-element array).
+     */
+    limit?: number;
+}
+export interface ChunkResult {
+    /** The split text chunks, each within the platform limit. */
+    chunks: string[];
+    /** Character limit that was applied (0 = unlimited). */
+    limit: number;
+    /** Total characters in the original text. */
+    totalLength: number;
+}
+/**
+ * Per-platform character limits for outgoing messages.
+ * 0 means unlimited - the text is returned as a single chunk.
+ */
+export declare const PLATFORM_LIMITS: Readonly<Record<ChatProviderId | 'default', number>>;
+/**
+ * Get the character limit for a platform.
+ * Returns 0 for unlimited platforms.
+ */
+export declare function getPlatformLimit(platform: ChatProviderId | string): number;
+/**
+ * Chunk text for a specific platform.
+ *
+ * @param text     - The text to chunk
+ * @param platform - Target platform ID (used to look up character limit)
+ * @param options  - Optional overrides for mode and limit
+ * @returns        A ChunkResult with the chunks array and metadata
+ *
+ * @example
+ * const { chunks } = chunkForPlatform(longText, 'discord');
+ * for (const chunk of chunks) await sendMessage(chunk);
+ */
+export declare function chunkForPlatform(text: string, platform: ChatProviderId | string, options?: ChunkOptions): ChunkResult;
+/**
+ * Simple helper: returns just the chunks array.
+ * Useful when you don't need the metadata.
+ */
+export declare function chunkText(text: string, platform: ChatProviderId | string, options?: ChunkOptions): string[];
+//# sourceMappingURL=chunk.d.ts.map

package/dist/chat/format/chunk.js

@@ -0,0 +1,253 @@
+/**
+ * Text Chunking Utility
+ *
+ * Splits long text into chunks that fit within per-platform message limits.
+ * Handles two splitting strategies:
+ * - length: split at word boundaries up to the character limit
+ * - newline: split at paragraph/newline boundaries
+ *
+ * Code blocks (```) are always kept intact - never split mid-block.
+ */
+// Platform limits
+/**
+ * Per-platform character limits for outgoing messages.
+ * 0 means unlimited - the text is returned as a single chunk.
+ */
+export const PLATFORM_LIMITS = {
+    telegram: 4096,
+    discord: 2000,
+    slack: 4000,
+    whatsapp: 4096,
+    matrix: 65536,
+    msteams: 28000,
+    googlechat: 4096,
+    irc: 512,
+    mattermost: 16383,
+    line: 5000,
+    webchat: 0,
+    // Remaining platforms default to 4000 (conservative safe value)
+    signal: 4000,
+    dingtalk: 4000,
+    wecom: 4000,
+    feishu: 4000,
+    qq: 4000,
+    nostr: 4000,
+    twitch: 4000,
+    zalo: 4000,
+    nextcloud: 4000,
+    imessage: 4000,
+    synology: 4000,
+    tlon: 4000,
+    'zalo-personal': 4000,
+    custom: 4000,
+    default: 4000,
+};
+/**
+ * Get the character limit for a platform.
+ * Returns 0 for unlimited platforms.
+ */
+export function getPlatformLimit(platform) {
+    const key = platform;
+    if (key in PLATFORM_LIMITS) {
+        return PLATFORM_LIMITS[key];
+    }
+    return PLATFORM_LIMITS.default;
+}
+/**
+ * Split text into alternating prose and code-block segments.
+ * Code blocks (delimited by ```) are marked so they are never split.
+ */
+function splitIntoSegments(text) {
+    const segments = [];
+    // Match fenced code blocks: ```optional-lang\n...\n```
+    const codeBlockPattern = /```[\s\S]*?```/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = codeBlockPattern.exec(text)) !== null) {
+        // Prose before this code block
+        if (match.index > lastIndex) {
+            segments.push({ text: text.slice(lastIndex, match.index), isCodeBlock: false });
+        }
+        // The code block itself
+        segments.push({ text: match[0], isCodeBlock: true });
+        lastIndex = match.index + match[0].length;
+    }
+    // Remaining prose after the last code block
+    if (lastIndex < text.length) {
+        segments.push({ text: text.slice(lastIndex), isCodeBlock: false });
+    }
+    return segments;
+}
+// Splitting strategies
+/**
+ * Split prose text by length, respecting word boundaries.
+ * Never cuts in the middle of a word.
+ */
+function splitByLength(text, limit) {
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= limit) {
+            chunks.push(remaining);
+            break;
+        }
+        // Find the last whitespace at or before the limit
+        let splitAt = limit;
+        const candidateSlice = remaining.slice(0, limit + 1);
+        const lastSpace = candidateSlice.lastIndexOf(' ');
+        const lastNewline = candidateSlice.lastIndexOf('\n');
+        const lastBreak = Math.max(lastSpace, lastNewline);
+        if (lastBreak > 0) {
+            splitAt = lastBreak;
+        }
+        // If no whitespace found, hard-split at limit (e.g. extremely long word)
+        chunks.push(remaining.slice(0, splitAt).trimEnd());
+        remaining = remaining.slice(splitAt).trimStart();
+    }
+    return chunks;
+}
+/**
+ * Split text at paragraph/newline boundaries.
+ * Accumulates paragraphs into a chunk until the limit would be exceeded,
+ * then starts a new chunk.
+ *
+ * If a single paragraph exceeds the limit, it is further split by length.
+ */
+function splitByNewline(text, limit) {
+    // Split on double-newlines (paragraphs) first, then single newlines
+    const paragraphs = text.split(/\n{2,}/);
+    const chunks = [];
+    let current = '';
+    for (const para of paragraphs) {
+        const trimmedPara = para.trim();
+        if (!trimmedPara)
+            continue;
+        const separator = current ? '\n\n' : '';
+        const candidate = current + separator + trimmedPara;
+        if (candidate.length <= limit) {
+            current = candidate;
+        }
+        else {
+            // Flush the current chunk
+            if (current) {
+                chunks.push(current);
+                current = '';
+            }
+            // Paragraph itself fits in a new chunk
+            if (trimmedPara.length <= limit) {
+                current = trimmedPara;
+            }
+            else {
+                // Paragraph is too large - fall back to length splitting
+                const subChunks = splitByLength(trimmedPara, limit);
+                const last = subChunks.pop();
+                chunks.push(...subChunks);
+                current = last ?? '';
+            }
+        }
+    }
+    if (current) {
+        chunks.push(current);
+    }
+    return chunks;
+}
+// Core chunking logic
+/**
+ * Chunk a text string so every chunk fits within `limit` characters.
+ * Code blocks are preserved - they may occupy their own chunk if large,
+ * but are never split mid-block.
+ */
+function chunkWithLimit(text, limit, mode) {
+    const segments = splitIntoSegments(text);
+    const resultChunks = [];
+    let currentChunk = '';
+    for (const segment of segments) {
+        if (segment.isCodeBlock) {
+            // If the code block alone exceeds the limit we still emit it intact
+            // (truncation is not acceptable for code blocks).
+            if (currentChunk) {
+                resultChunks.push(currentChunk.trimEnd());
+                currentChunk = '';
+            }
+            if (segment.text.length <= limit || limit === 0) {
+                resultChunks.push(segment.text);
+            }
+            else {
+                // Code block exceeds limit - emit as-is, callers must handle
+                resultChunks.push(segment.text);
+            }
+        }
+        else {
+            // Prose: split according to mode
+            const proseChunks = mode === 'newline'
+                ? splitByNewline(segment.text, limit)
+                : splitByLength(segment.text, limit);
+            for (let i = 0; i < proseChunks.length; i++) {
+                const prose = proseChunks[i];
+                if (i === 0 && currentChunk) {
+                    // Try to append the first prose chunk to whatever we have buffered
+                    const separator = currentChunk.endsWith('\n') ? '' : '\n\n';
+                    const candidate = currentChunk + separator + prose;
+                    if (candidate.length <= limit) {
+                        currentChunk = candidate;
+                        continue;
+                    }
+                    // Doesn't fit - flush the buffer first
+                    resultChunks.push(currentChunk.trimEnd());
+                    currentChunk = prose;
+                }
+                else if (currentChunk) {
+                    // Middle/last chunk from this segment: flush previous and start fresh
+                    resultChunks.push(currentChunk.trimEnd());
+                    currentChunk = prose;
+                }
+                else {
+                    currentChunk = prose;
+                }
+            }
+        }
+    }
+    if (currentChunk.trim()) {
+        resultChunks.push(currentChunk.trimEnd());
+    }
+    return resultChunks.filter(c => c.trim().length > 0);
+}
+// Public API
+/**
+ * Chunk text for a specific platform.
+ *
+ * @param text     - The text to chunk
+ * @param platform - Target platform ID (used to look up character limit)
+ * @param options  - Optional overrides for mode and limit
+ * @returns        A ChunkResult with the chunks array and metadata
+ *
+ * @example
+ * const { chunks } = chunkForPlatform(longText, 'discord');
+ * for (const chunk of chunks) await sendMessage(chunk);
+ */
+export function chunkForPlatform(text, platform, options = {}) {
+    const { mode = 'length' } = options;
+    const limit = options.limit !== undefined ? options.limit : getPlatformLimit(platform);
+    // Edge cases
+    if (!text) {
+        return { chunks: [], limit, totalLength: 0 };
+    }
+    // Unlimited or text fits in one chunk
+    if (limit === 0 || text.length <= limit) {
+        return { chunks: [text], limit, totalLength: text.length };
+    }
+    const chunks = chunkWithLimit(text, limit, mode);
+    return {
+        chunks,
+        limit,
+        totalLength: text.length,
+    };
+}
+/**
+ * Simple helper: returns just the chunks array.
+ * Useful when you don't need the metadata.
+ */
+export function chunkText(text, platform, options) {
+    return chunkForPlatform(text, platform, options).chunks;
+}
+//# sourceMappingURL=chunk.js.map