supaclaw 1.0.0

package/dist/context-manager.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Context Window Management
+ * Implements token budgeting, smart context selection, and lost-in-middle mitigation
+ */
+import { Message, Memory, Learning, Entity } from './index';
+export interface ContextBudget {
+    total: number;
+    systemPrompt: number;
+    recentMessages: number;
+    memories: number;
+    learnings: number;
+    entities: number;
+    reserve: number;
+}
+export interface ContextItem {
+    type: 'message' | 'memory' | 'learning' | 'entity';
+    content: string;
+    importance: number;
+    timestamp: string;
+    tokenCount: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ContextWindow {
+    items: ContextItem[];
+    totalTokens: number;
+    budget: ContextBudget;
+    truncated: boolean;
+}
+/**
+ * Estimates token count using rough heuristic
+ * 1 token ≈ 4 characters for English text
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimates token count more accurately using word count
+ * Better approximation: 1 token ≈ 0.75 words
+ */
+export declare function estimateTokensAccurate(text: string): number;
+/**
+ * Create a context budget for different model context windows
+ */
+export declare function createContextBudget(opts: {
+    modelContextSize?: number;
+    systemPromptSize?: number;
+    reserveSize?: number;
+    recentMessagesPct?: number;
+    memoriesPct?: number;
+    learningsPct?: number;
+    entitiesPct?: number;
+}): ContextBudget;
+/**
+ * Convert messages to context items
+ */
+export declare function messagesToContextItems(messages: Message[]): ContextItem[];
+/**
+ * Convert memories to context items
+ */
+export declare function memoriesToContextItems(memories: Memory[]): ContextItem[];
+/**
+ * Convert learnings to context items
+ */
+export declare function learningsToContextItems(learnings: Learning[]): ContextItem[];
+/**
+ * Convert entities to context items
+ */
+export declare function entitiesToContextItems(entities: Entity[]): ContextItem[];
+/**
+ * Select items within budget using smart prioritization
+ * Implements lost-in-middle mitigation by placing high-importance items at edges
+ */
+export declare function selectContextItems(items: ContextItem[], budget: number, opts?: {
+    recencyWeight?: number;
+    importanceWeight?: number;
+}): ContextItem[];
+/**
+ * Arrange items to mitigate "lost in the middle" effect
+ * Places highest-importance items at the beginning and end
+ * Medium-importance items go in the middle
+ *
+ * Research shows LLMs pay more attention to the beginning and end of context
+ */
+export declare function arrangeForLostInMiddle(items: ContextItem[]): ContextItem[];
+/**
+ * Build a complete context window with budget management
+ */
+export declare function buildContextWindow(opts: {
+    messages: Message[];
+    memories: Memory[];
+    learnings: Learning[];
+    entities: Entity[];
+    budget: ContextBudget;
+    useLostInMiddleFix?: boolean;
+    recencyWeight?: number;
+    importanceWeight?: number;
+}): ContextWindow;
+/**
+ * Format context window as string for injection into prompt
+ */
+export declare function formatContextWindow(window: ContextWindow, opts?: {
+    includeMetadata?: boolean;
+    groupByType?: boolean;
+}): string;
+/**
+ * Get context window stats
+ */
+export declare function getContextStats(window: ContextWindow): {
+    totalItems: number;
+    totalTokens: number;
+    budgetUsed: number;
+    budgetRemaining: number;
+    itemsByType: Record<string, number>;
+    truncated: boolean;
+};
+/**
+ * Adaptive context budgeting
+ * Adjusts budget allocation based on available content
+ */
+export declare function createAdaptiveBudget(opts: {
+    modelContextSize?: number;
+    messageCount: number;
+    memoryCount: number;
+    learningCount: number;
+    entityCount: number;
+}): ContextBudget;
+/**
+ * Model-specific context budgets
+ */
+export declare const MODEL_BUDGETS: {
+    'claude-3-opus': ContextBudget;
+    'claude-3-sonnet': ContextBudget;
+    'claude-3-haiku': ContextBudget;
+    'claude-3.5-sonnet': ContextBudget;
+    'gpt-4-turbo': ContextBudget;
+    'gpt-4': ContextBudget;
+    'gpt-3.5-turbo': ContextBudget;
+    'gemini-pro': ContextBudget;
+    'llama-3-70b': ContextBudget;
+    default: ContextBudget;
+};
+/**
+ * Get budget for a specific model
+ */
+export declare function getBudgetForModel(model: string): ContextBudget;

package/dist/context-manager.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * Context Window Management
+ * Implements token budgeting, smart context selection, and lost-in-middle mitigation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_BUDGETS = void 0;
+exports.estimateTokens = estimateTokens;
+exports.estimateTokensAccurate = estimateTokensAccurate;
+exports.createContextBudget = createContextBudget;
+exports.messagesToContextItems = messagesToContextItems;
+exports.memoriesToContextItems = memoriesToContextItems;
+exports.learningsToContextItems = learningsToContextItems;
+exports.entitiesToContextItems = entitiesToContextItems;
+exports.selectContextItems = selectContextItems;
+exports.arrangeForLostInMiddle = arrangeForLostInMiddle;
+exports.buildContextWindow = buildContextWindow;
+exports.formatContextWindow = formatContextWindow;
+exports.getContextStats = getContextStats;
+exports.createAdaptiveBudget = createAdaptiveBudget;
+exports.getBudgetForModel = getBudgetForModel;
+/**
+ * Estimates token count using rough heuristic
+ * 1 token ≈ 4 characters for English text
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Estimates token count more accurately using word count
+ * Better approximation: 1 token ≈ 0.75 words
+ */
+function estimateTokensAccurate(text) {
+    const words = text.trim().split(/\s+/).length;
+    return Math.ceil(words / 0.75);
+}
+/**
+ * Create a context budget for different model context windows
+ */
+function createContextBudget(opts) {
+    const total = opts.modelContextSize || 128000;
+    const systemPrompt = opts.systemPromptSize || 2000;
+    const reserve = opts.reserveSize || 4000;
+    const available = total - systemPrompt - reserve;
+    const recentMessagesPct = opts.recentMessagesPct || 0.4;
+    const memoriesPct = opts.memoriesPct || 0.3;
+    const learningsPct = opts.learningsPct || 0.2;
+    const entitiesPct = opts.entitiesPct || 0.1;
+    return {
+        total,
+        systemPrompt,
+        reserve,
+        recentMessages: Math.floor(available * recentMessagesPct),
+        memories: Math.floor(available * memoriesPct),
+        learnings: Math.floor(available * learningsPct),
+        entities: Math.floor(available * entitiesPct)
+    };
+}
+/**
+ * Convert messages to context items
+ */
+function messagesToContextItems(messages) {
+    return messages.map(msg => ({
+        type: 'message',
+        content: `${msg.role}: ${msg.content}`,
+        importance: msg.role === 'user' ? 0.8 : 0.6, // User messages slightly more important
+        timestamp: msg.created_at,
+        tokenCount: msg.token_count || estimateTokens(msg.content),
+        metadata: { id: msg.id, session_id: msg.session_id, ...msg.metadata }
+    }));
+}
+/**
+ * Convert memories to context items
+ */
+function memoriesToContextItems(memories) {
+    return memories.map(mem => ({
+        type: 'memory',
+        content: `[Memory: ${mem.category || 'general'}] ${mem.content}`,
+        importance: mem.importance,
+        timestamp: mem.created_at,
+        tokenCount: estimateTokens(mem.content),
+        metadata: { id: mem.id, category: mem.category, ...mem.metadata }
+    }));
+}
+/**
+ * Convert learnings to context items
+ */
+function learningsToContextItems(learnings) {
+    return learnings.map(learn => ({
+        type: 'learning',
+        content: `[Learning: ${learn.category}] ${learn.lesson}${learn.action ? '\nAction: ' + learn.action : ''}`,
+        importance: learn.severity === 'critical' ? 0.9 : learn.severity === 'warning' ? 0.7 : 0.5,
+        timestamp: learn.created_at,
+        tokenCount: estimateTokens(learn.lesson + (learn.action || '')),
+        metadata: { id: learn.id, severity: learn.severity, applied: learn.applied_count, ...learn.metadata }
+    }));
+}
+/**
+ * Convert entities to context items
+ */
+function entitiesToContextItems(entities) {
+    return entities.map(entity => ({
+        type: 'entity',
+        content: `[Entity: ${entity.entity_type}] ${entity.name}${entity.description ? ': ' + entity.description : ''}`,
+        importance: Math.min(entity.mention_count / 20, 1), // More mentions = more important
+        timestamp: entity.last_seen_at,
+        tokenCount: estimateTokens(entity.name + (entity.description || '')),
+        metadata: { id: entity.id, type: entity.entity_type, mentions: entity.mention_count }
+    }));
+}
+/**
+ * Select items within budget using smart prioritization
+ * Implements lost-in-middle mitigation by placing high-importance items at edges
+ */
+function selectContextItems(items, budget, opts = {}) {
+    const recencyWeight = opts.recencyWeight ?? 0.3;
+    const importanceWeight = opts.importanceWeight ?? 0.7;
+    // Calculate composite score for each item
+    const now = Date.now();
+    const itemsWithScores = items.map(item => {
+        const age = now - new Date(item.timestamp).getTime();
+        const daysSinceCreated = age / (1000 * 60 * 60 * 24);
+        // Recency score: exponential decay over 30 days
+        const recencyScore = Math.exp(-daysSinceCreated / 30);
+        // Composite score
+        const score = (importanceWeight * item.importance) + (recencyWeight * recencyScore);
+        return { item, score };
+    });
+    // Sort by score descending
+    itemsWithScores.sort((a, b) => b.score - a.score);
+    // Select items within budget
+    let totalTokens = 0;
+    const selected = [];
+    for (const { item } of itemsWithScores) {
+        if (totalTokens + item.tokenCount <= budget) {
+            selected.push(item);
+            totalTokens += item.tokenCount;
+        }
+    }
+    return selected;
+}
+/**
+ * Arrange items to mitigate "lost in the middle" effect
+ * Places highest-importance items at the beginning and end
+ * Medium-importance items go in the middle
+ *
+ * Research shows LLMs pay more attention to the beginning and end of context
+ */
+function arrangeForLostInMiddle(items) {
+    if (items.length <= 3) {
+        return items; // Too few items to rearrange
+    }
+    // Sort by importance
+    const sorted = [...items].sort((a, b) => b.importance - a.importance);
+    const arranged = [];
+    const half = Math.ceil(sorted.length / 2);
+    // High-importance items at beginning
+    for (let i = 0; i < half; i++) {
+        if (i % 2 === 0) {
+            arranged.push(sorted[i]);
+        }
+    }
+    // Medium-importance items in middle
+    const middle = sorted.slice(half);
+    arranged.push(...middle);
+    // Remaining high-importance items at end
+    for (let i = 0; i < half; i++) {
+        if (i % 2 === 1) {
+            arranged.push(sorted[i]);
+        }
+    }
+    return arranged;
+}
+/**
+ * Build a complete context window with budget management
+ */
+function buildContextWindow(opts) {
+    const { messages, memories, learnings, entities, budget, useLostInMiddleFix = true, recencyWeight, importanceWeight } = opts;
+    // Convert to context items
+    const messageItems = messagesToContextItems(messages);
+    const memoryItems = memoriesToContextItems(memories);
+    const learningItems = learningsToContextItems(learnings);
+    const entityItems = entitiesToContextItems(entities);
+    // Select within budget for each category
+    const selectedMessages = selectContextItems(messageItems, budget.recentMessages, {
+        recencyWeight,
+        importanceWeight
+    });
+    const selectedMemories = selectContextItems(memoryItems, budget.memories, {
+        recencyWeight,
+        importanceWeight
+    });
+    const selectedLearnings = selectContextItems(learningItems, budget.learnings, {
+        recencyWeight,
+        importanceWeight
+    });
+    const selectedEntities = selectContextItems(entityItems, budget.entities, {
+        recencyWeight,
+        importanceWeight
+    });
+    // Combine all items
+    let allItems = [
+        ...selectedMessages,
+        ...selectedMemories,
+        ...selectedLearnings,
+        ...selectedEntities
+    ];
+    // Apply lost-in-middle mitigation
+    if (useLostInMiddleFix) {
+        allItems = arrangeForLostInMiddle(allItems);
+    }
+    else {
+        // Default: chronological order
+        allItems.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    }
+    const totalTokens = allItems.reduce((sum, item) => sum + item.tokenCount, 0);
+    const truncated = messageItems.length > selectedMessages.length ||
+        memoryItems.length > selectedMemories.length ||
+        learningItems.length > selectedLearnings.length ||
+        entityItems.length > selectedEntities.length;
+    return {
+        items: allItems,
+        totalTokens,
+        budget,
+        truncated
+    };
+}
+/**
+ * Format context window as string for injection into prompt
+ */
+function formatContextWindow(window, opts = {}) {
+    const { items } = window;
+    const lines = [];
+    if (opts.groupByType) {
+        // Group by type
+        const messages = items.filter(i => i.type === 'message');
+        const memories = items.filter(i => i.type === 'memory');
+        const learnings = items.filter(i => i.type === 'learning');
+        const entities = items.filter(i => i.type === 'entity');
+        if (memories.length > 0) {
+            lines.push('# Relevant Memories');
+            lines.push('');
+            memories.forEach(m => lines.push(m.content));
+            lines.push('');
+        }
+        if (learnings.length > 0) {
+            lines.push('# Relevant Learnings');
+            lines.push('');
+            learnings.forEach(l => lines.push(l.content));
+            lines.push('');
+        }
+        if (entities.length > 0) {
+            lines.push('# Known Entities');
+            lines.push('');
+            entities.forEach(e => lines.push(e.content));
+            lines.push('');
+        }
+        if (messages.length > 0) {
+            lines.push('# Recent Conversation');
+            lines.push('');
+            messages.forEach(m => {
+                const content = m.content;
+                if (opts.includeMetadata && m.metadata) {
+                    lines.push(`${content} (importance: ${m.importance.toFixed(2)})`);
+                }
+                else {
+                    lines.push(content);
+                }
+            });
+        }
+    }
+    else {
+        // Chronological order
+        items.forEach(item => {
+            if (opts.includeMetadata) {
+                lines.push(`${item.content} [${item.type}, importance: ${item.importance.toFixed(2)}]`);
+            }
+            else {
+                lines.push(item.content);
+            }
+        });
+    }
+    return lines.join('\n');
+}
+/**
+ * Get context window stats
+ */
+function getContextStats(window) {
+    const itemsByType = {};
+    window.items.forEach(item => {
+        itemsByType[item.type] = (itemsByType[item.type] || 0) + 1;
+    });
+    const totalBudget = window.budget.recentMessages +
+        window.budget.memories +
+        window.budget.learnings +
+        window.budget.entities;
+    return {
+        totalItems: window.items.length,
+        totalTokens: window.totalTokens,
+        budgetUsed: window.totalTokens / totalBudget,
+        budgetRemaining: totalBudget - window.totalTokens,
+        itemsByType,
+        truncated: window.truncated
+    };
+}
+/**
+ * Adaptive context budgeting
+ * Adjusts budget allocation based on available content
+ */
+function createAdaptiveBudget(opts) {
+    const total = opts.modelContextSize || 128000;
+    const systemPrompt = 2000;
+    const reserve = 4000;
+    const available = total - systemPrompt - reserve;
+    // Calculate weights based on content availability
+    const totalItems = opts.messageCount + opts.memoryCount + opts.learningCount + opts.entityCount;
+    if (totalItems === 0) {
+        return createContextBudget({ modelContextSize: total });
+    }
+    const messagePct = opts.messageCount / totalItems;
+    const memoryPct = opts.memoryCount / totalItems;
+    const learningPct = opts.learningCount / totalItems;
+    const entityPct = opts.entityCount / totalItems;
+    // Normalize (ensure sum = 1)
+    const sum = messagePct + memoryPct + learningPct + entityPct;
+    return {
+        total,
+        systemPrompt,
+        reserve,
+        recentMessages: Math.floor(available * (messagePct / sum)),
+        memories: Math.floor(available * (memoryPct / sum)),
+        learnings: Math.floor(available * (learningPct / sum)),
+        entities: Math.floor(available * (entityPct / sum))
+    };
+}
+/**
+ * Model-specific context budgets
+ */
+exports.MODEL_BUDGETS = {
+    // Claude models
+    'claude-3-opus': createContextBudget({ modelContextSize: 200000 }),
+    'claude-3-sonnet': createContextBudget({ modelContextSize: 200000 }),
+    'claude-3-haiku': createContextBudget({ modelContextSize: 200000 }),
+    'claude-3.5-sonnet': createContextBudget({ modelContextSize: 200000 }),
+    // GPT models
+    'gpt-4-turbo': createContextBudget({ modelContextSize: 128000 }),
+    'gpt-4': createContextBudget({ modelContextSize: 8192 }),
+    'gpt-3.5-turbo': createContextBudget({ modelContextSize: 16384 }),
+    // Other models
+    'gemini-pro': createContextBudget({ modelContextSize: 32000 }),
+    'llama-3-70b': createContextBudget({ modelContextSize: 8192 }),
+    // Default
+    'default': createContextBudget({ modelContextSize: 128000 })
+};
+/**
+ * Get budget for a specific model
+ */
+function getBudgetForModel(model) {
+    return exports.MODEL_BUDGETS[model] || exports.MODEL_BUDGETS.default;
+}

package/dist/error-handling.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Error handling and retry logic for OpenClaw Memory
+ *
+ * Provides:
+ * - Custom error types
+ * - Retry logic with exponential backoff
+ * - Circuit breaker pattern
+ * - Error recovery strategies
+ */
+export declare class OpenClawError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+export declare class DatabaseError extends OpenClawError {
+    constructor(message: string, details?: unknown);
+}
+export declare class EmbeddingError extends OpenClawError {
+    constructor(message: string, details?: unknown);
+}
+export declare class ValidationError extends OpenClawError {
+    constructor(message: string, details?: unknown);
+}
+export declare class RateLimitError extends OpenClawError {
+    constructor(message: string, details?: unknown);
+}
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    shouldRetry?: (error: Error) => boolean;
+    onRetry?: (attempt: number, error: Error) => void;
+}
+/**
+ * Retry a function with exponential backoff
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Circuit breaker pattern
+ * Prevents cascading failures by failing fast when error rate is high
+ */
+export declare class CircuitBreaker {
+    private failureThreshold;
+    private recoveryTimeMs;
+    private successThreshold;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private state;
+    constructor(failureThreshold?: number, recoveryTimeMs?: number, // 1 minute
+    successThreshold?: number);
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    reset(): void;
+    getState(): {
+        state: "closed" | "open" | "half-open";
+        failures: number;
+        successes: number;
+        lastFailureTime: number;
+    };
+}
+/**
+ * Wrap database operations with error handling
+ */
+export declare function wrapDatabaseOperation<T>(operation: () => Promise<T>, errorContext: string): Promise<T>;
+/**
+ * Wrap embedding operations with error handling
+ */
+export declare function wrapEmbeddingOperation<T>(operation: () => Promise<T>, errorContext: string): Promise<T>;
+/**
+ * Validate inputs
+ */
+export declare function validateInput(condition: boolean, message: string, details?: unknown): void;
+/**
+ * Safe JSON parse
+ */
+export declare function safeJsonParse<T>(json: string, fallback: T): T;
+/**
+ * Safe async operation with timeout
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage?: string): Promise<T>;
+/**
+ * Graceful degradation helper
+ */
+export declare function gracefulFallback<T>(primary: () => Promise<T>, fallback: () => T | Promise<T>, errorContext: string): Promise<T>;
+/**
+ * Batch operation with error handling
+ * Continues processing even if some items fail
+ */
+export declare function batchWithErrorHandling<T, R>(items: T[], operation: (item: T) => Promise<R>, options?: {
+    continueOnError?: boolean;
+    onError?: (item: T, error: Error) => void;
+}): Promise<Array<{
+    success: boolean;
+    result?: R;
+    error?: Error;
+    item: T;
+}>>;