@compilr-dev/sdk 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -43,6 +43,8 @@ export { resolveProvider, detectProviderFromEnv, createProviderFromType } from '
 export { DEFAULT_MODELS, getContextWindow, DEFAULT_CONTEXT_WINDOW } from './models.js';
 export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
 export { assembleTools, deduplicateTools } from './tools.js';
+export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
+export type { MetaToolStats, MetaTools } from './meta-tools/index.js';
 export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
 export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';

package/dist/index.js

@@ -61,6 +61,10 @@ getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefa
 // =============================================================================
 export { assembleTools, deduplicateTools } from './tools.js';
 // =============================================================================
+// Meta-Tools Registry (dynamic tool loading for token reduction)
+// =============================================================================
+export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
+// =============================================================================
 // System Prompt Builder
 // =============================================================================
 export { 

package/dist/meta-tools/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Meta-tools — Dynamic tool loading for token reduction.
+ *
+ * @example
+ * ```typescript
+ * import { MetaToolsRegistry, createMetaTools } from '@compilr-dev/sdk';
+ *
+ * const registry = new MetaToolsRegistry();
+ * registry.initialize(myTools);
+ *
+ * const metaTools = createMetaTools(registry);
+ * // Use metaTools.getToolInfoTool as a direct tool
+ * // Use metaTools.createFallback() for transparent routing
+ * ```
+ */
+export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, type MetaToolStats, type MetaTools, } from './registry.js';

package/dist/meta-tools/index.js

@@ -0,0 +1,16 @@
+/**
+ * Meta-tools — Dynamic tool loading for token reduction.
+ *
+ * @example
+ * ```typescript
+ * import { MetaToolsRegistry, createMetaTools } from '@compilr-dev/sdk';
+ *
+ * const registry = new MetaToolsRegistry();
+ * registry.initialize(myTools);
+ *
+ * const metaTools = createMetaTools(registry);
+ * // Use metaTools.getToolInfoTool as a direct tool
+ * // Use metaTools.createFallback() for transparent routing
+ * ```
+ */
+export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './registry.js';

package/dist/meta-tools/registry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * MetaToolsRegistry — Instance-based meta-tools for SDK consumers.
+ *
+ * Replaces full tool declarations (~15K tokens for 49 tools) with:
+ * 1. A compact tool index in the system prompt (~800 tokens)
+ * 2. Three meta-tools: list_tools, get_tool_info, use_tool
+ * 3. A transparent fallback handler for direct tool calls
+ *
+ * Each agent gets its own registry instance, enabling multi-agent
+ * scenarios where each agent has a different tool set.
+ */
+import { type Tool, type ToolExecutionResult } from '@compilr-dev/agents';
+/**
+ * Statistics about the meta-tools registry.
+ */
+export interface MetaToolStats {
+    /** Total tools in the registry */
+    registeredTools: number;
+    /** Tools allowed by the current filter (or all if no filter) */
+    allowedTools: number;
+    /** Estimated token savings vs declaring all tools directly */
+    estimatedTokenSavings: number;
+}
+/**
+ * The set of meta-tools and fallback handler returned by createMetaTools().
+ */
+export interface MetaTools {
+    /** Lists available tools by category */
+    listToolsTool: Tool;
+    /** Returns the JSON schema for a tool's parameters */
+    getToolInfoTool: Tool;
+    /** Executes any registered tool by name */
+    useToolTool: Tool;
+    /** Creates a fallback handler for transparent tool routing */
+    createFallback: () => (name: string, input: Record<string, unknown>) => Promise<ToolExecutionResult | null>;
+}
+export declare class MetaToolsRegistry {
+    private readonly toolRegistry;
+    private readonly ajv;
+    private currentFilter;
+    /**
+     * Populate the registry with available tools.
+     * Call this once at startup with all tools that should be available via meta-tools.
+     */
+    initialize(tools: Tool[]): void;
+    /**
+     * Set the current tool filter for meta-registry access.
+     * Pass null or undefined to allow all tools.
+     */
+    setFilter(filter: string[] | null | undefined): void;
+    /**
+     * Get the current tool filter.
+     */
+    getFilter(): Set<string> | null;
+    /**
+     * Check if a tool is allowed by the current filter.
+     */
+    isToolAllowed(name: string): boolean;
+    /**
+     * Get all registered tools.
+     */
+    getRegisteredTools(): Tool[];
+    /**
+     * Get a tool by name from the registry.
+     */
+    getTool(name: string): Tool | undefined;
+    /**
+     * Get count of registered tools.
+     */
+    getToolCount(): number;
+    /**
+     * Generate tool index for the system prompt.
+     * Groups tools by category and shows signatures.
+     */
+    generateToolIndex(): string;
+    /**
+     * Get the full system prompt section (prefix + index).
+     */
+    getToolIndexForSystemPrompt(): string;
+    /**
+     * Get registry statistics.
+     */
+    getStats(): MetaToolStats;
+    /**
+     * Validate arguments against a tool's schema.
+     * Returns null if valid, or an error message string.
+     */
+    validateArgs(toolName: string, args: Record<string, unknown>): string | null;
+}
+/**
+ * Create the three meta-tools + fallback handler, all bound to a registry instance.
+ */
+export declare function createMetaTools(registry: MetaToolsRegistry): MetaTools;
+export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get the exact JSON schema. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";

package/dist/meta-tools/registry.js

@@ -0,0 +1,406 @@
+/**
+ * MetaToolsRegistry — Instance-based meta-tools for SDK consumers.
+ *
+ * Replaces full tool declarations (~15K tokens for 49 tools) with:
+ * 1. A compact tool index in the system prompt (~800 tokens)
+ * 2. Three meta-tools: list_tools, get_tool_info, use_tool
+ * 3. A transparent fallback handler for direct tool calls
+ *
+ * Each agent gets its own registry instance, enabling multi-agent
+ * scenarios where each agent has a different tool set.
+ */
+import Ajv from 'ajv';
+import { defineTool, createSuccessResult, createErrorResult, } from '@compilr-dev/agents';
+// =============================================================================
+// MetaToolsRegistry class
+// =============================================================================
+export class MetaToolsRegistry {
+    toolRegistry = new Map();
+    ajv = new Ajv({ allErrors: true });
+    currentFilter = null;
+    /**
+     * Populate the registry with available tools.
+     * Call this once at startup with all tools that should be available via meta-tools.
+     */
+    initialize(tools) {
+        this.toolRegistry.clear();
+        for (const tool of tools) {
+            this.toolRegistry.set(tool.definition.name, tool);
+        }
+    }
+    /**
+     * Set the current tool filter for meta-registry access.
+     * Pass null or undefined to allow all tools.
+     */
+    setFilter(filter) {
+        this.currentFilter = filter ? new Set(filter) : null;
+    }
+    /**
+     * Get the current tool filter.
+     */
+    getFilter() {
+        return this.currentFilter;
+    }
+    /**
+     * Check if a tool is allowed by the current filter.
+     */
+    isToolAllowed(name) {
+        if (!this.currentFilter) {
+            return true;
+        }
+        return this.currentFilter.has(name);
+    }
+    /**
+     * Get all registered tools.
+     */
+    getRegisteredTools() {
+        return Array.from(this.toolRegistry.values());
+    }
+    /**
+     * Get a tool by name from the registry.
+     */
+    getTool(name) {
+        return this.toolRegistry.get(name);
+    }
+    /**
+     * Get count of registered tools.
+     */
+    getToolCount() {
+        return this.toolRegistry.size;
+    }
+    /**
+     * Generate tool index for the system prompt.
+     * Groups tools by category and shows signatures.
+     */
+    generateToolIndex() {
+        const tools = this.getRegisteredTools();
+        if (tools.length === 0) {
+            return '(No tools registered in meta-tool registry)';
+        }
+        // Filter by allowed tools
+        const allowedTools = tools.filter((t) => this.isToolAllowed(t.definition.name));
+        // Group tools by prefix
+        const groups = {};
+        for (const tool of allowedTools) {
+            const prefix = tool.definition.name.split('_')[0];
+            const category = getCategoryName(prefix);
+            groups[category] = groups[category] ?? [];
+            groups[category].push(tool);
+        }
+        // Build index with signatures
+        const lines = [];
+        for (const [category, categoryTools] of Object.entries(groups).sort()) {
+            lines.push(`### ${category}`);
+            for (const tool of categoryTools) {
+                const signature = buildToolSignature(tool);
+                lines.push(`- ${signature}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Get the full system prompt section (prefix + index).
+     */
+    getToolIndexForSystemPrompt() {
+        return META_TOOLS_SYSTEM_PROMPT_PREFIX + this.generateToolIndex();
+    }
+    /**
+     * Get registry statistics.
+     */
+    getStats() {
+        const registeredTools = this.toolRegistry.size;
+        const allowedTools = this.getRegisteredTools().filter((t) => this.isToolAllowed(t.definition.name)).length;
+        // ~300 tokens per full tool definition, ~800 tokens for the index
+        const tokensPerTool = 300;
+        const estimatedTokenSavings = registeredTools * tokensPerTool - 800;
+        return {
+            registeredTools,
+            allowedTools,
+            estimatedTokenSavings: Math.max(0, estimatedTokenSavings),
+        };
+    }
+    /**
+     * Validate arguments against a tool's schema.
+     * Returns null if valid, or an error message string.
+     */
+    validateArgs(toolName, args) {
+        const tool = this.toolRegistry.get(toolName);
+        if (!tool) {
+            return `Unknown tool: '${toolName}'`;
+        }
+        const schema = tool.definition.inputSchema;
+        const validate = this.ajv.compile(schema);
+        const valid = validate(args);
+        if (!valid) {
+            return formatValidationErrors(validate.errors);
+        }
+        return null;
+    }
+}
+// =============================================================================
+// Meta-tool factory
+// =============================================================================
+/**
+ * Create the three meta-tools + fallback handler, all bound to a registry instance.
+ */
+export function createMetaTools(registry) {
+    // -------------------------------------------------------------------------
+    // list_tools
+    // -------------------------------------------------------------------------
+    const listToolsTool = defineTool({
+        name: 'list_tools',
+        description: 'List all available specialized tools. Call this first to see what tools are available ' +
+            'before using use_tool. Optionally filter by category.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                category: {
+                    type: 'string',
+                    description: 'Optional category filter (e.g., "git", "project", "workitem", "plan", "anchor")',
+                },
+            },
+            required: [],
+        },
+        execute: ({ category }) => {
+            const tools = registry.getRegisteredTools();
+            // Filter by allowed tools
+            let filteredTools = tools.filter((t) => registry.isToolAllowed(t.definition.name));
+            // Filter by category if specified
+            if (category) {
+                const prefix = category.toLowerCase();
+                filteredTools = filteredTools.filter((t) => t.definition.name.toLowerCase().startsWith(prefix));
+            }
+            const toolList = filteredTools.map((t) => ({
+                name: t.definition.name,
+                description: t.definition.description.split('.')[0],
+            }));
+            return Promise.resolve(createSuccessResult({
+                count: toolList.length,
+                tools: toolList,
+                hint: 'Use get_tool_info("tool_name") to see full parameter details for any tool.',
+            }));
+        },
+    });
+    // -------------------------------------------------------------------------
+    // get_tool_info
+    // -------------------------------------------------------------------------
+    const getToolInfoTool = defineTool({
+        name: 'get_tool_info',
+        description: "Get the exact JSON schema for a tool's parameters. " +
+            'MUST be called before passing any parameters to a Tool Index tool. ' +
+            'Zero-parameter calls do not need this.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tool_name: {
+                    type: 'string',
+                    description: 'Name of the tool from the Tool Index',
+                },
+            },
+            required: ['tool_name'],
+        },
+        execute: ({ tool_name }) => {
+            const tool = registry.getTool(tool_name);
+            if (!tool) {
+                const availableTools = registry
+                    .getRegisteredTools()
+                    .map((t) => t.definition.name)
+                    .slice(0, 10);
+                return Promise.resolve(createErrorResult(`Unknown tool: '${tool_name}'. ` +
+                    `Available tools include: ${availableTools.join(', ')}... ` +
+                    `Check the Tool Index for the full list.`));
+            }
+            return Promise.resolve(createSuccessResult({
+                name: tool.definition.name,
+                description: tool.definition.description,
+                parameters: tool.definition.inputSchema,
+            }));
+        },
+    });
+    // -------------------------------------------------------------------------
+    // use_tool
+    // -------------------------------------------------------------------------
+    const useToolTool = defineTool({
+        name: 'use_tool',
+        description: 'Execute any tool from the Tool Index. Check the Tool Index for ' +
+            'available tools and their parameters. For complex parameters, ' +
+            'call get_tool_info first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tool_name: {
+                    type: 'string',
+                    description: 'Name of the tool to execute (from Tool Index)',
+                },
+                args: {
+                    type: 'object',
+                    description: 'Arguments to pass to the tool. Must match the tool schema.',
+                    additionalProperties: true,
+                },
+            },
+            required: ['tool_name', 'args'],
+        },
+        execute: async ({ tool_name, args }) => {
+            // 0. Check tool filter
+            if (!registry.isToolAllowed(tool_name)) {
+                const filter = registry.getFilter();
+                const allowedTools = filter
+                    ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
+                    : [];
+                return createErrorResult(`Tool '${tool_name}' is not available for this agent. ` +
+                    `Your available meta-registry tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''} ` +
+                    `Call list_tools() to see all available tools.`);
+            }
+            // 1. Find the tool
+            const tool = registry.getTool(tool_name);
+            if (!tool) {
+                const availableTools = registry
+                    .getRegisteredTools()
+                    .filter((t) => registry.isToolAllowed(t.definition.name))
+                    .map((t) => t.definition.name)
+                    .slice(0, 10);
+                return createErrorResult(`Unknown tool: '${tool_name}'. ` +
+                    `Available tools include: ${availableTools.join(', ')}... ` +
+                    `Check the Tool Index for the full list.`);
+            }
+            // 2. Validate args
+            const validationError = registry.validateArgs(tool_name, args);
+            if (validationError) {
+                return createErrorResult(`Invalid arguments for '${tool_name}': ${validationError}. ` +
+                    `Expected schema: ${JSON.stringify(tool.definition.inputSchema, null, 2)}. ` +
+                    `Hint: Call get_tool_info("${tool_name}") to see full parameter details.`);
+            }
+            // 3. Execute the tool
+            try {
+                const result = await tool.execute(args);
+                // Enhance result with clear top-level message for smaller models
+                if (result.success && typeof result.result === 'object' && result.result !== null) {
+                    const innerResult = result.result;
+                    const innerMessage = typeof innerResult.message === 'string' ? innerResult.message : null;
+                    return createSuccessResult({
+                        tool: tool_name,
+                        status: 'completed',
+                        message: innerMessage ?? `Tool '${tool_name}' executed successfully.`,
+                        result: innerResult,
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                return createErrorResult(`Tool '${tool_name}' execution failed: ${errorMessage}`);
+            }
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Fallback handler factory
+    // -------------------------------------------------------------------------
+    function createFallback() {
+        return async (name, input) => {
+            // Check if tool exists in registry
+            const tool = registry.getTool(name);
+            if (!tool) {
+                return null; // Not in registry — let default "not found" error through
+            }
+            // Check tool filter
+            if (!registry.isToolAllowed(name)) {
+                const filter = registry.getFilter();
+                const allowedTools = filter
+                    ? Array.from(filter).filter((t) => registry.getTool(t) !== undefined)
+                    : [];
+                return createErrorResult(`Tool '${name}' is not available for this agent. ` +
+                    `Available tools: ${allowedTools.slice(0, 10).join(', ')}${allowedTools.length > 10 ? '...' : ''}`);
+            }
+            // Validate args
+            const validationError = registry.validateArgs(name, input);
+            if (validationError) {
+                return createErrorResult(`Invalid arguments for '${name}': ${validationError}. ` +
+                    `Call get_tool_info("${name}") to get the exact parameter schema before retrying.`);
+            }
+            // Execute the tool
+            try {
+                return await tool.execute(input);
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                return createErrorResult(`Tool '${name}' execution failed: ${errorMessage}`);
+            }
+        };
+    }
+    return {
+        listToolsTool: listToolsTool,
+        getToolInfoTool: getToolInfoTool,
+        useToolTool: useToolTool,
+        createFallback,
+    };
+}
+// =============================================================================
+// System prompt constant
+// =============================================================================
+export const META_TOOLS_SYSTEM_PROMPT_PREFIX = `
+## Tool Index (Specialized Tools)
+
+These tools are called **exactly like direct tools** — just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.
+
+**IMPORTANT — These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**
+
+**Parameter Rules:**
+- For **zero-parameter calls**: call the tool directly (e.g., \`workitem_query()\`, \`git_status()\`).
+- For **calls WITH parameters**: you MUST call \`get_tool_info("tool_name")\` first to get the exact JSON schema. The signatures below are summaries only — do NOT guess parameter structure from them.
+- After a failed tool call, always call \`get_tool_info()\` before retrying.
+
+`;
+// =============================================================================
+// Helpers (internal)
+// =============================================================================
+/**
+ * Map tool prefix to category name.
+ */
+function getCategoryName(prefix) {
+    const categoryMap = {
+        git: 'Git Operations',
+        project: 'Project Management',
+        workitem: 'Work Items',
+        plan: 'Planning',
+        document: 'Documents',
+        anchor: 'Context Anchors',
+        backlog: 'Backlog',
+        detect: 'Analysis',
+        find: 'Analysis',
+        run: 'Runners',
+    };
+    return categoryMap[prefix] ?? 'Other';
+}
+/**
+ * Build a concise signature for a tool.
+ * e.g., "git_commit(message: string, files?: string[]) - Create a commit"
+ */
+function buildToolSignature(tool) {
+    const schema = tool.definition.inputSchema;
+    const params = [];
+    if (schema.properties) {
+        const required = new Set(schema.required ?? []);
+        for (const [name, prop] of Object.entries(schema.properties)) {
+            const isRequired = required.has(name);
+            const type = prop.type ?? 'any';
+            params.push(isRequired ? `${name}: ${type}` : `${name}?: ${type}`);
+        }
+    }
+    const paramsStr = params.length > 0 ? params.join(', ') : '';
+    const desc = tool.definition.description.split('.')[0]; // First sentence
+    return `${tool.definition.name}(${paramsStr}) - ${desc}`;
+}
+/**
+ * Format AJV validation errors into a readable string.
+ */
+function formatValidationErrors(errors) {
+    if (!errors || errors.length === 0) {
+        return 'Unknown validation error';
+    }
+    const messages = errors.map((e) => {
+        const path = e.dataPath ? e.dataPath.replace(/^\./, '') : 'args';
+        return `${path}: ${e.message ?? 'validation failed'}`;
+    });
+    return messages.join('; ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -52,6 +52,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "ajv": "^6.14.0"
+  },
   "peerDependencies": {
     "@compilr-dev/agents": "^0.3.14",
     "@compilr-dev/agents-coding": "^1.0.2"