profclaw 2.0.0 → 2.4.0

package/dist/agents/tool-loader.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool Loader
+ *
+ * Manages tool categorization and lazy loading for the agentic system.
+ * Provides search over tool categories so the AI can discover and enable
+ * tools on demand without paying the full context cost of all schemas.
+ */
+import type { ToolDefinition } from '../chat/execution/types.js';
+export interface ToolCategory {
+    /** Unique slug for this category (e.g. "file_ops") */
+    name: string;
+    /** Human-readable description shown to users and the AI */
+    description: string;
+    /** Keywords used for fuzzy search / auto-load decisions */
+    keywords: string[];
+    /** Canonical tool names that belong to this category */
+    tools: string[];
+    /** When true, these tools are always included in every session */
+    alwaysLoaded: boolean;
+}
+export declare class ToolLoader {
+    private allTools;
+    private categories;
+    private loadedToolNames;
+    constructor(allTools: Map<string, ToolDefinition>);
+    /**
+     * Return the subset of tools that are always loaded (core session tools).
+     */
+    getCoreTools(): ToolDefinition[];
+    /**
+     * Return all tools that have been loaded for the current session,
+     * including always_loaded plus any dynamically loaded categories/tools.
+     */
+    getSessionTools(): ToolDefinition[];
+    /**
+     * Search categories by query string.
+     * Matches against category name, description, and keywords using
+     * case-insensitive substring matching; results are ranked by score.
+     */
+    search(query: string): ToolCategory[];
+    /**
+     * Load all tools belonging to a named category into the active session.
+     * Silently ignores tool names that are not registered.
+     */
+    loadCategory(categoryName: string): void;
+    /**
+     * Load a single tool by name into the active session.
+     * Silently ignores names that are not registered.
+     */
+    loadTool(toolName: string): void;
+    /**
+     * Return all registered categories.
+     */
+    getCategories(): ToolCategory[];
+    /**
+     * Register a custom category.
+     * Will overwrite any existing category with the same name.
+     */
+    registerCategory(category: ToolCategory): void;
+    /**
+     * Check whether a specific tool is currently loaded into the session.
+     */
+    isLoaded(toolName: string): boolean;
+}
+//# sourceMappingURL=tool-loader.d.ts.map

package/dist/agents/tool-loader.js

@@ -0,0 +1,273 @@
+/**
+ * Tool Loader
+ *
+ * Manages tool categorization and lazy loading for the agentic system.
+ * Provides search over tool categories so the AI can discover and enable
+ * tools on demand without paying the full context cost of all schemas.
+ */
+// Built-in Category Definitions
+const BUILT_IN_CATEGORIES = [
+    {
+        name: 'always_loaded',
+        description: 'Core tools that are always available in every session',
+        keywords: ['core', 'always', 'base', 'default', 'essential'],
+        tools: [
+            'read_file',
+            'write_file',
+            'search_files',
+            'exec',
+            'git_status',
+            'git_commit',
+            'complete_task',
+            'search_available_tools',
+        ],
+        alwaysLoaded: true,
+    },
+    {
+        name: 'file_ops',
+        description: 'Extended file system operations: edit, grep, patch, directory tree',
+        keywords: ['file', 'filesystem', 'read', 'write', 'edit', 'grep', 'search', 'patch', 'directory'],
+        tools: [
+            'read_file',
+            'write_file',
+            'search_files',
+            'grep',
+            'edit_file',
+            'directory_tree',
+            'patch_apply',
+            'multi_patch',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'browser',
+        description: 'Browser automation tools for web scraping and UI testing',
+        keywords: ['browser', 'playwright', 'navigate', 'click', 'screenshot', 'web', 'automation', 'scrape'],
+        tools: [
+            'browser_navigate',
+            'browser_click',
+            'browser_fill',
+            'browser_screenshot',
+            'browser_evaluate',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'integration',
+        description: 'Third-party integration tools: Slack, Discord, Telegram, screen capture, clipboard',
+        keywords: ['slack', 'discord', 'telegram', 'notification', 'clipboard', 'screen', 'capture', 'integration'],
+        tools: [
+            'slack_actions',
+            'discord_actions',
+            'telegram_actions',
+            'screen_capture',
+            'clipboard_read',
+            'clipboard_write',
+            'notify',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'git_advanced',
+        description: 'Advanced Git operations beyond status and commit',
+        keywords: ['git', 'diff', 'log', 'branch', 'stash', 'remote', 'merge', 'rebase', 'version control'],
+        tools: [
+            'git_status',
+            'git_diff',
+            'git_log',
+            'git_commit',
+            'git_branch',
+            'git_stash',
+            'git_remote',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'canvas',
+        description: 'Canvas rendering and image generation tools',
+        keywords: ['canvas', 'image', 'render', 'draw', 'generate', 'visual', 'graphic'],
+        tools: [
+            'canvas_render',
+            'openai_image_gen',
+            'image_analyze',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'voice',
+        description: 'Text-to-speech and voice synthesis tools',
+        keywords: ['voice', 'tts', 'speech', 'audio', 'speak', 'synthesize'],
+        tools: [
+            'tts_speak',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'memory',
+        description: 'Conversation memory management: search, retrieval, and statistics',
+        keywords: ['memory', 'remember', 'recall', 'search', 'context', 'history', 'retrieve'],
+        tools: [
+            'memory_search',
+            'memory_get',
+            'memory_stats',
+        ],
+        alwaysLoaded: false,
+    },
+    {
+        name: 'system',
+        description: 'System information, environment variables, and process management',
+        keywords: ['system', 'env', 'environment', 'process', 'info', 'hardware', 'os', 'which', 'path'],
+        tools: [
+            'env',
+            'system_info',
+            'process_list',
+            'path_info',
+            'which',
+        ],
+        alwaysLoaded: false,
+    },
+];
+// Tool Loader
+export class ToolLoader {
+    allTools;
+    categories;
+    loadedToolNames;
+    constructor(allTools) {
+        this.allTools = allTools;
+        this.categories = new Map();
+        this.loadedToolNames = new Set();
+        // Register built-in categories
+        for (const category of BUILT_IN_CATEGORIES) {
+            this.categories.set(category.name, category);
+        }
+        // Pre-load always_loaded tools
+        const alwaysLoaded = this.categories.get('always_loaded');
+        if (alwaysLoaded) {
+            for (const toolName of alwaysLoaded.tools) {
+                if (this.allTools.has(toolName)) {
+                    this.loadedToolNames.add(toolName);
+                }
+            }
+        }
+    }
+    /**
+     * Return the subset of tools that are always loaded (core session tools).
+     */
+    getCoreTools() {
+        const core = this.categories.get('always_loaded');
+        if (!core)
+            return [];
+        return core.tools
+            .map((name) => this.allTools.get(name))
+            .filter((tool) => tool !== undefined);
+    }
+    /**
+     * Return all tools that have been loaded for the current session,
+     * including always_loaded plus any dynamically loaded categories/tools.
+     */
+    getSessionTools() {
+        return Array.from(this.loadedToolNames)
+            .map((name) => this.allTools.get(name))
+            .filter((tool) => tool !== undefined);
+    }
+    /**
+     * Search categories by query string.
+     * Matches against category name, description, and keywords using
+     * case-insensitive substring matching; results are ranked by score.
+     */
+    search(query) {
+        if (!query.trim()) {
+            return Array.from(this.categories.values());
+        }
+        const terms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 0);
+        const scored = [];
+        for (const category of this.categories.values()) {
+            let score = 0;
+            for (const term of terms) {
+                // Exact name match gets highest weight
+                if (category.name === term) {
+                    score += 10;
+                }
+                else if (category.name.includes(term)) {
+                    score += 5;
+                }
+                // Description match
+                if (category.description.toLowerCase().includes(term)) {
+                    score += 3;
+                }
+                // Keyword match
+                for (const keyword of category.keywords) {
+                    if (keyword === term) {
+                        score += 4;
+                    }
+                    else if (keyword.includes(term)) {
+                        score += 2;
+                    }
+                }
+                // Tool name match
+                for (const toolName of category.tools) {
+                    if (toolName.includes(term)) {
+                        score += 1;
+                    }
+                }
+            }
+            if (score > 0) {
+                scored.push({ category, score });
+            }
+        }
+        return scored
+            .sort((a, b) => b.score - a.score)
+            .map((s) => s.category);
+    }
+    /**
+     * Load all tools belonging to a named category into the active session.
+     * Silently ignores tool names that are not registered.
+     */
+    loadCategory(categoryName) {
+        const category = this.categories.get(categoryName);
+        if (!category) {
+            return;
+        }
+        for (const toolName of category.tools) {
+            if (this.allTools.has(toolName)) {
+                this.loadedToolNames.add(toolName);
+            }
+        }
+    }
+    /**
+     * Load a single tool by name into the active session.
+     * Silently ignores names that are not registered.
+     */
+    loadTool(toolName) {
+        if (this.allTools.has(toolName)) {
+            this.loadedToolNames.add(toolName);
+        }
+    }
+    /**
+     * Return all registered categories.
+     */
+    getCategories() {
+        return Array.from(this.categories.values());
+    }
+    /**
+     * Register a custom category.
+     * Will overwrite any existing category with the same name.
+     */
+    registerCategory(category) {
+        this.categories.set(category.name, category);
+        // If the new category is marked always_loaded, immediately load its tools
+        if (category.alwaysLoaded) {
+            this.loadCategory(category.name);
+        }
+    }
+    /**
+     * Check whether a specific tool is currently loaded into the session.
+     */
+    isLoaded(toolName) {
+        return this.loadedToolNames.has(toolName);
+    }
+}
+//# sourceMappingURL=tool-loader.js.map

package/dist/agents/tool-selector.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Tool Selector
+ *
+ * Sends only the tool schemas that are likely needed on a given turn instead
+ * of every registered tool. Selection is a cheap, deterministic heuristic (no
+ * LLM call): a small core set, plus groups whose keywords appear in the user
+ * message or whose tools were used recently. The model can request more groups
+ * with the `load_tools` meta-tool.
+ *
+ * Cache stability: within a session the set of loaded groups only grows, and
+ * the output is always sorted by tool name, so the tool prefix of the prompt
+ * stays byte-identical between turns unless a new group is genuinely needed.
+ *
+ * Env:
+ *   PROFCLAW_TOOL_SELECTION           off/0/false/no disables (default on)
+ *   PROFCLAW_TOOL_SELECTION_MIN_TOOLS skip selection when the tool count is at
+ *                                     or below this number (default 12)
+ *   PROFCLAW_TOOL_SELECTION_KEEP_UNGROUPED
+ *                                     keep tools that match no group, such as
+ *                                     MCP or plugin tools (default true)
+ */
+import { z } from 'zod';
+export interface SelectableTool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export interface ToolGroup {
+    name: string;
+    description: string;
+    /** Exact tool names, or prefixes ending in `*` */
+    tools: string[];
+    /** Matched against the lowercased user message */
+    keywords: RegExp;
+}
+export declare const LOAD_TOOLS_NAME = "load_tools";
+export declare const FETCH_RESULT_NAME = "fetch_result";
+/** Tools that are always sent. Keep this small. */
+export declare const CORE_TOOL_NAMES: readonly string[];
+export declare const TOOL_GROUPS: readonly ToolGroup[];
+export declare function isToolSelectionEnabled(): boolean;
+/** Group name a tool belongs to, or undefined for core/ungrouped tools. */
+export declare function groupOfTool(name: string): string | undefined;
+export declare class ToolSelectorSession {
+    /** Groups loaded so far. Only ever grows, which keeps the prefix stable. */
+    private readonly loaded;
+    getLoadedGroups(): string[];
+    /** Mark groups loaded. Returns the names that were valid. */
+    loadGroups(names: string[]): string[];
+    /** Keep the group of a tool that was just executed loaded. */
+    noteToolUse(toolName: string): void;
+    /** Add groups whose keywords match the user message. */
+    noteMessage(message: string): string[];
+    /**
+     * Select tools for this turn. Output is sorted by name and, apart from
+     * newly loaded groups, identical across calls in the same session.
+     */
+    select<T extends SelectableTool>(all: readonly T[], message?: string): T[];
+}
+export declare function getToolSelectorSession(sessionId: string): ToolSelectorSession;
+export declare function resetToolSelectorSessions(): void;
+declare const LoadToolsSchema: z.ZodObject<{
+    groups: z.ZodArray<z.ZodString, "many">;
+    invoke: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodString;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }, {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    groups: string[];
+    invoke?: {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    } | undefined;
+}, {
+    groups: string[];
+    invoke?: {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+declare const FetchResultSchema: z.ZodObject<{
+    result_id: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    length: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    result_id: string;
+    length?: number | undefined;
+    offset?: number | undefined;
+}, {
+    result_id: string;
+    length?: number | undefined;
+    offset?: number | undefined;
+}>;
+export type LoadToolsArgs = z.infer<typeof LoadToolsSchema>;
+export type FetchResultArgs = z.infer<typeof FetchResultSchema>;
+export declare function parseLoadToolsArgs(args: unknown): LoadToolsArgs | null;
+export declare function parseFetchResultArgs(args: unknown): FetchResultArgs | null;
+/** Stable, compact meta-tool definitions. Description text must not vary. */
+export declare function getMetaTools(includeFetchResult: boolean): SelectableTool[];
+/** Rough tokens for one tool schema as sent to the provider (about 4 chars per token). */
+export declare function estimateToolTokens(tool: SelectableTool): number;
+export declare function estimateToolsTokens(tools: readonly SelectableTool[]): number;
+/** Compact JSON schema for a tool, used in load_tools results. */
+export declare function describeTool(tool: SelectableTool): {
+    name: string;
+    description: string;
+    parameters: unknown;
+};
+/** Tools belonging to a named group, sorted by name. */
+export declare function toolsInGroup<T extends SelectableTool>(all: readonly T[], groupName: string): T[];
+/**
+ * Select tools for one agentic request and append the meta-tools. When
+ * selection is disabled the input list is returned unchanged.
+ */
+export declare function selectToolsForRequest<T extends SelectableTool>(tools: readonly T[], sessionId: string, message: string): Array<T | SelectableTool>;
+export {};
+//# sourceMappingURL=tool-selector.d.ts.map