profclaw 0.0.1-beta.1

package/dist/chat/execution/rate-limiter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Rate Limiter
+ *
+ * Enforces rate limits on tool executions per user, conversation, and tool.
+ * Uses sliding window algorithm for accurate rate limiting.
+ */
+export interface RateLimitConfig {
+    userLimit: number;
+    userWindowMs: number;
+    conversationLimit: number;
+    conversationWindowMs: number;
+    defaultToolLimit: number;
+    defaultToolWindowMs: number;
+    globalLimit: number;
+    globalWindowMs: number;
+    enabled: boolean;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetAt: number;
+    retryAfter?: number;
+    limitType?: 'user' | 'conversation' | 'tool' | 'global';
+}
+export declare class RateLimiter {
+    private config;
+    private userWindows;
+    private conversationWindows;
+    private toolWindows;
+    private globalWindow;
+    private toolOverrides;
+    private cleanupTimer;
+    constructor(config?: Partial<RateLimitConfig>);
+    /**
+     * Check if a request is allowed and consume a token if so
+     */
+    check(context: {
+        userId?: string;
+        conversationId: string;
+        toolName: string;
+    }): RateLimitResult;
+    /**
+     * Get current rate limit status without consuming a token
+     */
+    getStatus(context: {
+        userId?: string;
+        conversationId: string;
+        toolName: string;
+    }): RateLimitResult;
+    /**
+     * Set tool-specific rate limit
+     */
+    setToolLimit(toolName: string, limit: number, windowMs?: number): void;
+    /**
+     * Remove tool-specific rate limit
+     */
+    removeToolLimit(toolName: string): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(updates: Partial<RateLimitConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Reset all rate limit windows
+     */
+    reset(): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+    private checkWindow;
+    private getRemainingForWindow;
+    private getResetTime;
+    private cleanup;
+    /**
+     * Evict oldest entries from a window map if it exceeds MAX_WINDOW_ENTRIES.
+     * Prevents unbounded memory growth from many unique keys.
+     */
+    private evictOldestEntries;
+}
+export declare function getRateLimiter(): RateLimiter;
+export declare function initRateLimiter(config?: Partial<RateLimitConfig>): RateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/chat/execution/rate-limiter.js

@@ -0,0 +1,305 @@
+/**
+ * Rate Limiter
+ *
+ * Enforces rate limits on tool executions per user, conversation, and tool.
+ * Uses sliding window algorithm for accurate rate limiting.
+ */
+import { logger } from '../../utils/logger.js';
+// Constants
+const DEFAULT_CONFIG = {
+    userLimit: 100,
+    userWindowMs: 60_000, // 100 per minute per user
+    conversationLimit: 50,
+    conversationWindowMs: 60_000, // 50 per minute per conversation
+    defaultToolLimit: 30,
+    defaultToolWindowMs: 60_000, // 30 per minute per tool
+    globalLimit: 500,
+    globalWindowMs: 60_000, // 500 per minute globally
+    enabled: true,
+};
+const CLEANUP_INTERVAL_MS = 60_000;
+const MAX_WINDOW_ENTRIES = parseInt(process.env['RATE_LIMIT_MAX_WINDOWS'] ?? '5000', 10);
+// Rate Limiter
+export class RateLimiter {
+    config;
+    userWindows = new Map();
+    conversationWindows = new Map();
+    toolWindows = new Map();
+    globalWindow = { timestamps: [] };
+    toolOverrides = new Map();
+    cleanupTimer = null;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Start cleanup timer
+        this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+    }
+    /**
+     * Check if a request is allowed and consume a token if so
+     */
+    check(context) {
+        if (!this.config.enabled) {
+            return {
+                allowed: true,
+                limit: Infinity,
+                remaining: Infinity,
+                resetAt: Date.now(),
+            };
+        }
+        const now = Date.now();
+        // Check global limit first
+        const globalResult = this.checkWindow(this.globalWindow, this.config.globalLimit, this.config.globalWindowMs, now);
+        if (!globalResult.allowed) {
+            return { ...globalResult, limitType: 'global' };
+        }
+        // Check user limit
+        if (context.userId) {
+            const userKey = `user:${context.userId}`;
+            let userWindow = this.userWindows.get(userKey);
+            if (!userWindow) {
+                userWindow = { timestamps: [] };
+                this.userWindows.set(userKey, userWindow);
+            }
+            const userResult = this.checkWindow(userWindow, this.config.userLimit, this.config.userWindowMs, now);
+            if (!userResult.allowed) {
+                return { ...userResult, limitType: 'user' };
+            }
+        }
+        // Check conversation limit
+        const convKey = `conv:${context.conversationId}`;
+        let convWindow = this.conversationWindows.get(convKey);
+        if (!convWindow) {
+            convWindow = { timestamps: [] };
+            this.conversationWindows.set(convKey, convWindow);
+        }
+        const convResult = this.checkWindow(convWindow, this.config.conversationLimit, this.config.conversationWindowMs, now);
+        if (!convResult.allowed) {
+            return { ...convResult, limitType: 'conversation' };
+        }
+        // Check tool limit
+        const toolKey = `tool:${context.toolName}`;
+        let toolWindow = this.toolWindows.get(toolKey);
+        if (!toolWindow) {
+            toolWindow = { timestamps: [] };
+            this.toolWindows.set(toolKey, toolWindow);
+        }
+        const toolOverride = this.toolOverrides.get(context.toolName);
+        const toolLimit = toolOverride?.limit ?? this.config.defaultToolLimit;
+        const toolWindowMs = toolOverride?.windowMs ?? this.config.defaultToolWindowMs;
+        const toolResult = this.checkWindow(toolWindow, toolLimit, toolWindowMs, now);
+        if (!toolResult.allowed) {
+            return { ...toolResult, limitType: 'tool' };
+        }
+        // All checks passed - consume tokens
+        this.globalWindow.timestamps.push(now);
+        if (context.userId) {
+            this.userWindows.get(`user:${context.userId}`).timestamps.push(now);
+        }
+        convWindow.timestamps.push(now);
+        toolWindow.timestamps.push(now);
+        // Return the most restrictive remaining count
+        const remaining = Math.min(globalResult.remaining - 1, context.userId ? this.getRemainingForWindow(this.userWindows.get(`user:${context.userId}`), this.config.userLimit, this.config.userWindowMs, now) : Infinity, convResult.remaining - 1, toolResult.remaining - 1);
+        return {
+            allowed: true,
+            limit: Math.min(this.config.globalLimit, context.userId ? this.config.userLimit : Infinity, this.config.conversationLimit, toolLimit),
+            remaining: Math.max(0, remaining),
+            resetAt: Math.min(globalResult.resetAt, context.userId ? this.getResetTime(this.userWindows.get(`user:${context.userId}`), this.config.userWindowMs, now) : Infinity, convResult.resetAt, toolResult.resetAt),
+        };
+    }
+    /**
+     * Get current rate limit status without consuming a token
+     */
+    getStatus(context) {
+        if (!this.config.enabled) {
+            return {
+                allowed: true,
+                limit: Infinity,
+                remaining: Infinity,
+                resetAt: Date.now(),
+            };
+        }
+        const now = Date.now();
+        const globalRemaining = this.getRemainingForWindow(this.globalWindow, this.config.globalLimit, this.config.globalWindowMs, now);
+        let userRemaining = Infinity;
+        if (context.userId) {
+            const userWindow = this.userWindows.get(`user:${context.userId}`);
+            if (userWindow) {
+                userRemaining = this.getRemainingForWindow(userWindow, this.config.userLimit, this.config.userWindowMs, now);
+            }
+            else {
+                userRemaining = this.config.userLimit;
+            }
+        }
+        const convWindow = this.conversationWindows.get(`conv:${context.conversationId}`);
+        const convRemaining = convWindow
+            ? this.getRemainingForWindow(convWindow, this.config.conversationLimit, this.config.conversationWindowMs, now)
+            : this.config.conversationLimit;
+        const toolOverride = this.toolOverrides.get(context.toolName);
+        const toolLimit = toolOverride?.limit ?? this.config.defaultToolLimit;
+        const toolWindowMs = toolOverride?.windowMs ?? this.config.defaultToolWindowMs;
+        const toolWindow = this.toolWindows.get(`tool:${context.toolName}`);
+        const toolRemaining = toolWindow
+            ? this.getRemainingForWindow(toolWindow, toolLimit, toolWindowMs, now)
+            : toolLimit;
+        const remaining = Math.min(globalRemaining, userRemaining, convRemaining, toolRemaining);
+        return {
+            allowed: remaining > 0,
+            limit: Math.min(this.config.globalLimit, context.userId ? this.config.userLimit : Infinity, this.config.conversationLimit, toolLimit),
+            remaining,
+            resetAt: now + Math.min(this.config.globalWindowMs, context.userId ? this.config.userWindowMs : Infinity, this.config.conversationWindowMs, toolWindowMs),
+        };
+    }
+    /**
+     * Set tool-specific rate limit
+     */
+    setToolLimit(toolName, limit, windowMs) {
+        this.toolOverrides.set(toolName, {
+            limit,
+            windowMs: windowMs ?? this.config.defaultToolWindowMs,
+        });
+        logger.info(`[RateLimit] Set tool limit: ${toolName} = ${limit}`, { component: 'RateLimiter' });
+    }
+    /**
+     * Remove tool-specific rate limit
+     */
+    removeToolLimit(toolName) {
+        this.toolOverrides.delete(toolName);
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        logger.info('[RateLimit] Config updated', { component: 'RateLimiter', config: this.config });
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Reset all rate limit windows
+     */
+    reset() {
+        this.userWindows.clear();
+        this.conversationWindows.clear();
+        this.toolWindows.clear();
+        this.globalWindow.timestamps = [];
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    // Private Methods
+    checkWindow(window, limit, windowMs, now) {
+        // Remove expired timestamps
+        const cutoff = now - windowMs;
+        window.timestamps = window.timestamps.filter(t => t > cutoff);
+        const remaining = limit - window.timestamps.length;
+        const resetAt = window.timestamps.length > 0
+            ? window.timestamps[0] + windowMs
+            : now + windowMs;
+        if (remaining <= 0) {
+            const retryAfter = Math.ceil((resetAt - now) / 1000);
+            return {
+                allowed: false,
+                limit,
+                remaining: 0,
+                resetAt,
+                retryAfter: Math.max(1, retryAfter),
+            };
+        }
+        return {
+            allowed: true,
+            limit,
+            remaining,
+            resetAt,
+        };
+    }
+    getRemainingForWindow(window, limit, windowMs, now) {
+        const cutoff = now - windowMs;
+        const validTimestamps = window.timestamps.filter(t => t > cutoff);
+        return limit - validTimestamps.length;
+    }
+    getResetTime(window, windowMs, now) {
+        const cutoff = now - windowMs;
+        const validTimestamps = window.timestamps.filter(t => t > cutoff);
+        return validTimestamps.length > 0
+            ? validTimestamps[0] + windowMs
+            : now + windowMs;
+    }
+    cleanup() {
+        const now = Date.now();
+        const maxWindowMs = Math.max(this.config.userWindowMs, this.config.conversationWindowMs, this.config.defaultToolWindowMs, this.config.globalWindowMs);
+        const cutoff = now - maxWindowMs;
+        // Clean up user windows
+        for (const [key, window] of this.userWindows) {
+            window.timestamps = window.timestamps.filter(t => t > cutoff);
+            if (window.timestamps.length === 0) {
+                this.userWindows.delete(key);
+            }
+        }
+        // Clean up conversation windows
+        for (const [key, window] of this.conversationWindows) {
+            window.timestamps = window.timestamps.filter(t => t > cutoff);
+            if (window.timestamps.length === 0) {
+                this.conversationWindows.delete(key);
+            }
+        }
+        // Clean up tool windows
+        for (const [key, window] of this.toolWindows) {
+            window.timestamps = window.timestamps.filter(t => t > cutoff);
+            if (window.timestamps.length === 0) {
+                this.toolWindows.delete(key);
+            }
+        }
+        // Clean up global window
+        this.globalWindow.timestamps = this.globalWindow.timestamps.filter(t => t > cutoff);
+        // Evict oldest entries if any window map exceeds the cap
+        this.evictOldestEntries(this.userWindows);
+        this.evictOldestEntries(this.conversationWindows);
+        this.evictOldestEntries(this.toolWindows);
+    }
+    /**
+     * Evict oldest entries from a window map if it exceeds MAX_WINDOW_ENTRIES.
+     * Prevents unbounded memory growth from many unique keys.
+     */
+    evictOldestEntries(windowMap) {
+        if (windowMap.size <= MAX_WINDOW_ENTRIES)
+            return;
+        const sorted = [...windowMap.entries()]
+            .sort((a, b) => {
+            const latestA = a[1].timestamps.length > 0 ? Math.max(...a[1].timestamps) : 0;
+            const latestB = b[1].timestamps.length > 0 ? Math.max(...b[1].timestamps) : 0;
+            return latestA - latestB;
+        });
+        const toRemove = sorted.slice(0, sorted.length - MAX_WINDOW_ENTRIES);
+        for (const [key] of toRemove) {
+            windowMap.delete(key);
+        }
+        if (toRemove.length > 0) {
+            logger.info(`[RateLimit] Evicted ${toRemove.length} stale window entries`, { component: 'RateLimiter' });
+        }
+    }
+}
+// Singleton
+let rateLimiter = null;
+export function getRateLimiter() {
+    if (!rateLimiter) {
+        rateLimiter = new RateLimiter();
+    }
+    return rateLimiter;
+}
+export function initRateLimiter(config) {
+    if (rateLimiter) {
+        rateLimiter.destroy();
+    }
+    rateLimiter = new RateLimiter(config);
+    return rateLimiter;
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/chat/execution/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool Registry
+ *
+ * Central registry for all available AI tools.
+ * Converts tool definitions to AI-compatible schemas.
+ */
+import type { ToolDefinition, ToolRegistry, ToolCategory, AIToolSchema, ToolFilterOptions } from './types.js';
+export declare class ToolRegistryImpl implements ToolRegistry {
+    private tools;
+    /**
+     * Register a tool
+     */
+    register<TParams, TResult>(tool: ToolDefinition<TParams, TResult>): void;
+    /**
+     * Unregister a tool
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a tool by name
+     */
+    get(name: string): ToolDefinition | undefined;
+    /**
+     * List all tools or filter by category
+     */
+    list(category?: ToolCategory): ToolDefinition[];
+    /**
+     * Get tools in AI function calling format, optionally filtered by tier and token budget.
+     */
+    getForAI(options?: ToolFilterOptions): AIToolSchema[];
+    /**
+     * Get tools filtered for a specific model's capability tier.
+     * Uses the tool router to classify the model and apply appropriate tier filters.
+     * Preferred over getForAI() when the model ID is known.
+     */
+    getForModel(modelId: string, conversationId?: string): AIToolSchema[];
+    /**
+     * Get tools for specific categories
+     */
+    getForAIByCategory(categories: ToolCategory[]): AIToolSchema[];
+    /**
+     * Get tool descriptions for system prompt
+     */
+    getDescriptions(): string;
+    private toAISchema;
+    private buildDescription;
+    /**
+     * Trim schemas to fit within a token budget (approximate).
+     * Prioritizes essential > standard > full tier tools.
+     */
+    private applyTokenBudget;
+    private formatCategory;
+}
+export declare function getToolRegistry(): ToolRegistryImpl;
+//# sourceMappingURL=registry.d.ts.map

package/dist/chat/execution/registry.js

@@ -0,0 +1,220 @@
+/**
+ * Tool Registry
+ *
+ * Central registry for all available AI tools.
+ * Converts tool definitions to AI-compatible schemas.
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { logger } from '../../utils/logger.js';
+import { filterToolsForModel } from './tool-router.js';
+// Tool Registry Implementation
+export class ToolRegistryImpl {
+    tools = new Map();
+    /**
+     * Register a tool
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            logger.warn(`[ToolRegistry] Overwriting existing tool: ${tool.name}`, { component: 'ToolRegistry' });
+        }
+        this.tools.set(tool.name, tool);
+        logger.info(`[ToolRegistry] Registered tool: ${tool.name} (${tool.category})`, { component: 'ToolRegistry' });
+    }
+    /**
+     * Unregister a tool
+     */
+    unregister(name) {
+        const existed = this.tools.has(name);
+        this.tools.delete(name);
+        if (existed) {
+            logger.info(`[ToolRegistry] Unregistered tool: ${name}`, { component: 'ToolRegistry' });
+        }
+        return existed;
+    }
+    /**
+     * Get a tool by name
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * List all tools or filter by category
+     */
+    list(category) {
+        const tools = Array.from(this.tools.values());
+        if (category) {
+            return tools.filter((t) => t.category === category);
+        }
+        return tools;
+    }
+    /**
+     * Get tools in AI function calling format, optionally filtered by tier and token budget.
+     */
+    getForAI(options) {
+        let tools = Array.from(this.tools.values());
+        // Filter by availability
+        tools = tools.filter((t) => {
+            if (t.isAvailable) {
+                return t.isAvailable().available;
+            }
+            return true;
+        });
+        // Filter by tier (essential < standard < full)
+        if (options?.tier) {
+            const tierOrder = { essential: 0, standard: 1, full: 2 };
+            const maxTier = tierOrder[options.tier];
+            const promotedSet = new Set(options?.promote ?? []);
+            tools = tools.filter((t) => {
+                // Promoted tools bypass tier filtering
+                if (promotedSet.has(t.name))
+                    return true;
+                const toolTier = t.tier ?? 'standard';
+                return tierOrder[toolTier] <= maxTier;
+            });
+        }
+        // Convert to AI schemas
+        let schemas = tools.map((tool) => this.toAISchema(tool, options?.capabilityLevel));
+        // Apply token budget if specified
+        if (options?.maxSchemaTokens) {
+            schemas = this.applyTokenBudget(schemas, options.maxSchemaTokens);
+        }
+        return schemas;
+    }
+    /**
+     * Get tools filtered for a specific model's capability tier.
+     * Uses the tool router to classify the model and apply appropriate tier filters.
+     * Preferred over getForAI() when the model ID is known.
+     */
+    getForModel(modelId, conversationId) {
+        let tools = Array.from(this.tools.values());
+        // Filter by availability first
+        tools = tools.filter((t) => {
+            if (t.isAvailable) {
+                return t.isAvailable().available;
+            }
+            return true;
+        });
+        // Apply model-aware tier filtering via tool router
+        tools = filterToolsForModel(tools, modelId, conversationId);
+        return tools.map((tool) => this.toAISchema(tool));
+    }
+    /**
+     * Get tools for specific categories
+     */
+    getForAIByCategory(categories) {
+        return Array.from(this.tools.values())
+            .filter((t) => categories.includes(t.category))
+            .map((tool) => this.toAISchema(tool));
+    }
+    /**
+     * Get tool descriptions for system prompt
+     */
+    getDescriptions() {
+        const tools = Array.from(this.tools.values());
+        const grouped = new Map();
+        for (const tool of tools) {
+            const existing = grouped.get(tool.category) ?? [];
+            existing.push(tool);
+            grouped.set(tool.category, existing);
+        }
+        const lines = ['## Available Tools\n'];
+        for (const [category, categoryTools] of grouped) {
+            lines.push(`### ${this.formatCategory(category)}\n`);
+            for (const tool of categoryTools) {
+                lines.push(`- **${tool.name}**: ${tool.description}`);
+                if (tool.securityLevel !== 'safe') {
+                    lines.push(`  _(Security: ${tool.securityLevel})_`);
+                }
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    // Private Methods
+    toAISchema(tool, capabilityLevel) {
+        // Convert Zod schema to JSON Schema
+        const jsonSchema = zodToJsonSchema(tool.parameters, {
+            $refStrategy: 'none',
+            target: 'openAi',
+        });
+        // Extract properties and required from JSON schema
+        const schemaObj = jsonSchema;
+        return {
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: this.buildDescription(tool, capabilityLevel),
+                parameters: {
+                    type: 'object',
+                    properties: schemaObj.properties ?? {},
+                    required: schemaObj.required,
+                },
+            },
+        };
+    }
+    buildDescription(tool, capabilityLevel) {
+        // For basic models, use short one-liner descriptions to save tokens
+        if (capabilityLevel === 'basic') {
+            // First sentence only
+            const firstSentence = tool.description.split(/\.\s/)[0];
+            return firstSentence.endsWith('.') ? firstSentence : `${firstSentence}.`;
+        }
+        let desc = tool.description;
+        // Add security note for non-safe tools
+        if (tool.securityLevel === 'dangerous') {
+            desc += '\n\n⚠️ This tool requires approval before execution.';
+        }
+        else if (tool.securityLevel === 'moderate') {
+            desc += '\n\nNote: This tool may require approval depending on the command.';
+        }
+        // Add examples only for reasoning models (saves tokens for instruction models)
+        if (capabilityLevel !== 'instruction' && tool.examples?.length) {
+            desc += '\n\nExamples:';
+            for (const example of tool.examples.slice(0, 2)) {
+                desc += `\n- ${example.description}`;
+            }
+        }
+        return desc;
+    }
+    /**
+     * Trim schemas to fit within a token budget (approximate).
+     * Prioritizes essential > standard > full tier tools.
+     */
+    applyTokenBudget(schemas, maxTokens) {
+        let totalTokens = 0;
+        const result = [];
+        for (const schema of schemas) {
+            // Rough estimate: 4 chars per token for JSON-stringified schema
+            const schemaTokens = Math.ceil(JSON.stringify(schema).length / 4);
+            if (totalTokens + schemaTokens > maxTokens && result.length > 0) {
+                break;
+            }
+            totalTokens += schemaTokens;
+            result.push(schema);
+        }
+        return result;
+    }
+    formatCategory(category) {
+        const names = {
+            execution: 'Command Execution',
+            filesystem: 'File System',
+            web: 'Web & Search',
+            data: 'Data & APIs',
+            system: 'System Information',
+            profclaw: 'profClaw Operations',
+            memory: 'Memory Management',
+            browser: 'Browser Automation',
+            custom: 'Custom Tools',
+        };
+        return names[category] ?? category;
+    }
+}
+// Singleton
+let toolRegistry = null;
+export function getToolRegistry() {
+    if (!toolRegistry) {
+        toolRegistry = new ToolRegistryImpl();
+    }
+    return toolRegistry;
+}
+//# sourceMappingURL=registry.js.map