@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/tools.d.ts

@@ -1,15 +1,80 @@
 /**
  * Tool Registry Setup
  *
- * Configures all available tools from @compilr-dev/agents
- * and @compilr-dev/agents-coding packages.
+ * Configures all available tools from @compilr-dev/sdk
+ * (which re-exports from @compilr-dev/agents and @compilr-dev/agents-coding).
+ *
+ * ARCHITECTURE (Meta-Tools):
+ * - DIRECT TOOLS: Always available, called by name (most common operations)
+ * - META-REGISTRY TOOLS: Available via use_tool() (specialized operations)
+ *
+ * This reduces token overhead from ~15K to ~2K per request.
+ *
+ * SINGLE SOURCE OF TRUTH:
+ * Tool names are defined in tool-names.ts (a dependency-free module).
+ * This file re-exports them for convenience. Import from here or tool-names.ts.
  */
+export { TOOL_NAMES, type ToolName, DIRECT_TOOL_NAMES, META_TOOL_NAMES, META_REGISTRY_TOOL_NAMES, getAllToolNames, } from './tool-names.js';
+import { TodoStore, type Tool } from '@compilr-dev/sdk';
+export declare const todoStore: TodoStore;
+import { setMetaToolFilter, getRegisteredMetaTools } from './tools/meta-tools.js';
+export { setMetaToolFilter, getRegisteredMetaTools };
 /**
  * Creates the tool registry with all available tools.
  * Returns tools as-is - the Agent.registerTools() method handles typing.
+ *
+ * @deprecated Use createDirectToolRegistry() + initializeMetaTools() instead
  */
 export declare function createToolRegistry(): unknown[];
 /**
  * Returns a minimal set of tools for basic testing.
  */
 export declare function createMinimalToolRegistry(): unknown[];
+/**
+ * Get direct tools that are always available.
+ * These are declared normally and can be called by name.
+ */
+export declare function getDirectTools(): Tool[];
+/**
+ * Get meta-tools for agent registration.
+ * Only get_tool_info is kept as a direct tool — use_tool and list_tools
+ * are no longer needed since the fallback handler routes calls transparently.
+ */
+export declare function getMetaTools(): Tool[];
+/**
+ * Create a fallback handler for the tool registry.
+ * When the agent calls a tool not in the direct registry, this handler
+ * checks the meta-registry and executes it transparently.
+ */
+export declare function createToolFallback(): (name: string, input: Record<string, unknown>) => Promise<import('@compilr-dev/sdk').ToolExecutionResult | null>;
+/**
+ * Initialize the meta-tool registry with specialized tools.
+ * Call this once at startup.
+ */
+export declare function initializeMetaTools(): void;
+/**
+ * Get the tool index for the system prompt.
+ * This lists all meta-registry tools with their signatures.
+ */
+export declare function getToolIndexForSystemPrompt(): string;
+/**
+ * Get count of meta-registry tools.
+ */
+export declare function getMetaToolsCount(): number;
+/**
+ * Check if meta-tools mode is enabled.
+ * Returns true if the meta-tool registry has been initialized.
+ */
+export declare function isMetaToolsEnabled(): boolean;
+/**
+ * Get tool statistics for debugging/display.
+ */
+export declare function getToolStats(): {
+    directTools: number;
+    metaRegistryTools: number;
+    totalTools: number;
+    estimatedDirectTokens: number;
+    estimatedMetaTokens: number;
+    estimatedLegacyTokens: number;
+    tokenSavings: number;
+};

package/dist/tools.js

@@ -1,14 +1,39 @@
 /**
  * Tool Registry Setup
  *
- * Configures all available tools from @compilr-dev/agents
- * and @compilr-dev/agents-coding packages.
+ * Configures all available tools from @compilr-dev/sdk
+ * (which re-exports from @compilr-dev/agents and @compilr-dev/agents-coding).
+ *
+ * ARCHITECTURE (Meta-Tools):
+ * - DIRECT TOOLS: Always available, called by name (most common operations)
+ * - META-REGISTRY TOOLS: Available via use_tool() (specialized operations)
+ *
+ * This reduces token overhead from ~15K to ~2K per request.
+ *
+ * SINGLE SOURCE OF TRUTH:
+ * Tool names are defined in tool-names.ts (a dependency-free module).
+ * This file re-exports them for convenience. Import from here or tool-names.ts.
  */
-import { readFileTool, writeFileTool, createBashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool as originalTodoWriteTool, todoReadTool, defineTool, } from '@compilr-dev/agents';
+// Re-export tool names from the dependency-free module
+// This breaks circular dependencies while maintaining a single source of truth
+export { TOOL_NAMES, DIRECT_TOOL_NAMES, META_TOOL_NAMES, META_REGISTRY_TOOL_NAMES, getAllToolNames, } from './tool-names.js';
+// =============================================================================
+// TOOL IMPORTS
+// =============================================================================
+import { readFileTool, writeFileTool, createBashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, createTodoTools, defineTool, } from '@compilr-dev/sdk';
+// Create todo tools with shared store (includes claim/handoff)
+const todoToolsResult = createTodoTools();
+const originalTodoWriteTool = todoToolsResult.todoWrite;
+const todoReadTool = todoToolsResult.todoRead;
+const todoClaimTool = todoToolsResult.todoClaim;
+const todoHandoffTool = todoToolsResult.todoHandoff;
+// Explicit type annotation avoids TS2742 when importing createTodoTools via @compilr-dev/sdk
+export const todoStore = todoToolsResult.store;
 const todoWriteTool = defineTool({
     name: 'todo_write',
-    description: 'Update the task list. Provide the complete list of todos. ' +
-        'Use this to track progress on multi-step tasks.',
+    description: 'Update the SESSION todo list (shown in footer). These are ephemeral tasks for the current session only. ' +
+        'For persistent project backlog items, use workitem_* tools instead. ' +
+        'Provide the complete list of todos to replace the current list.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -35,6 +60,15 @@ const todoWriteTool = defineTool({
                             type: 'number',
                             description: 'Priority (higher = more important)',
                         },
+                        owner: {
+                            type: 'string',
+                            description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned.',
+                        },
+                        blockedBy: {
+                            type: 'array',
+                            items: { type: 'number' },
+                            description: 'Array of 1-based task numbers this task depends on (e.g., [3, 4] means blocked by task #3 and #4)',
+                        },
                     },
                     required: ['content', 'status'],
                 },
@@ -49,63 +83,151 @@ const todoWriteTool = defineTool({
             status: todo.status,
             activeForm: todo.activeForm,
             priority: todo.priority,
+            owner: todo.owner,
+            blockedBy: todo.blockedBy,
         }));
         // Filter out empty todos and provide fallback
         const validTodos = normalizedTodos.map((todo) => ({
             ...todo,
             content: todo.content || 'Untitled task',
         }));
-        // Debug: log what we're sending (can be removed later)
-        // console.error('[DEBUG todo_write] Input:', JSON.stringify(input, null, 2));
-        // console.error('[DEBUG todo_write] Normalized:', JSON.stringify(validTodos, null, 2));
         // Call the original tool with normalized input
         const result = await originalTodoWriteTool.execute({ todos: validTodos });
-        // Debug: log result
-        // console.error('[DEBUG todo_write] Result:', JSON.stringify(result, null, 2));
         return result;
     },
+    silent: true,
 });
 // Create bash tool with longer timeout (2 minutes instead of 30 seconds)
 const bashTool = createBashTool({
     timeout: 120000, // 2 minutes
 });
-import { gitStatusTool, gitDiffTool, gitLogTool, gitCommitTool, gitBranchTool, detectProjectTool, findProjectRootTool, runTestsTool, runLintTool, } from '@compilr-dev/agents-coding';
+import { 
+// Git tools (basic)
+gitStatusTool, gitDiffTool, gitLogTool, gitCommitTool, gitBranchTool, 
+// Git tools (advanced)
+gitStashTool, gitBlameTool, gitFileHistoryTool, 
+// Project detection
+detectProjectTool, findProjectRootTool, 
+// Smart runners
+runTestsTool, runLintTool, runBuildTool, runFormatTool, 
+// Code search
+findDefinitionTool, findReferencesTool, findTodosTool, 
+// Dependency analysis
+checkOutdatedTool, findVulnerabilitiesTool, 
+// Testing analysis
+analyzeTestCoverageTool, 
+// Unified analysis (auto-detect language)
+getFileStructureTool, getComplexityTool, } from '@compilr-dev/sdk';
 // Local tools
-import { backlogReadTool, backlogWriteTool } from './tools/backlog.js';
 import { askUserTool } from './tools/ask-user.js';
 import { askUserSimpleTool } from './tools/ask-user-simple.js';
+import { delegateTool } from './tools/delegate.js';
+import { delegateBackgroundTool } from './tools/delegate-background.js';
+import { delegationStatusTool } from './tools/delegation-status.js';
+import { handoffTool } from './tools/handoff.js';
+import { guideTool } from './tools/guide-tool.js';
+// DB tools for project, work item, document, plan, backlog, anchor, artifact, and episode management
+import { allDbTools } from './tools/db-tools.js';
+// Meta-tools for dynamic tool loading
+import { initializeMetaToolRegistry, generateToolIndex, getMetaToolCount, META_TOOLS_SYSTEM_PROMPT_PREFIX, setMetaToolFilter, getRegisteredMetaTools, createMetaToolFallback, getToolInfoTool, } from './tools/meta-tools.js';
+// Re-export for use in agent.ts
+export { setMetaToolFilter, getRegisteredMetaTools };
+// =============================================================================
+// DIRECT TOOLS - Always available, called by name
+// =============================================================================
+/**
+ * Direct tools are the most frequently used tools.
+ * These are always available and can be called directly by name.
+ * Estimated: ~3,500 tokens for definitions
+ */
+const DIRECT_TOOLS = [
+    // File operations (most common)
+    readFileTool,
+    writeFileTool,
+    editTool,
+    // Shell (very common)
+    bashTool,
+    bashOutputTool,
+    killShellTool,
+    // Search (very common)
+    globTool,
+    grepTool,
+    // Task tracking (always needed)
+    todoWriteTool,
+    todoReadTool,
+    todoClaimTool,
+    todoHandoffTool,
+    // User interaction (always needed)
+    askUserTool,
+    askUserSimpleTool,
+    // Delegation (coordinator only)
+    delegateTool,
+    // Background delegation (coordinator mode)
+    delegateBackgroundTool,
+    // Handoff (specialist-to-specialist)
+    handoffTool,
+    // CLI documentation (always available)
+    guideTool,
+];
+// =============================================================================
+// META-REGISTRY TOOLS - Available via use_tool()
+// =============================================================================
+/**
+ * Meta-registry tools are specialized tools available via use_tool().
+ * Instead of declaring their full schemas (~12K tokens), we:
+ * 1. Add them to a registry
+ * 2. Generate a tool index for the system prompt (~800 tokens)
+ * 3. Let the agent call them via use_tool("tool_name", {args})
+ */
+const META_REGISTRY_TOOLS = [
+    // Git operations (basic)
+    gitStatusTool,
+    gitDiffTool,
+    gitLogTool,
+    gitCommitTool,
+    gitBranchTool,
+    // Git operations (advanced)
+    gitStashTool,
+    gitBlameTool,
+    gitFileHistoryTool,
+    // Project detection
+    detectProjectTool,
+    findProjectRootTool,
+    // Smart runners
+    runTestsTool,
+    runLintTool,
+    runBuildTool,
+    runFormatTool,
+    // Code search (language-agnostic)
+    findDefinitionTool,
+    findReferencesTool,
+    findTodosTool,
+    // Dependency analysis
+    checkOutdatedTool,
+    findVulnerabilitiesTool,
+    // Testing analysis
+    analyzeTestCoverageTool,
+    // Unified analysis (auto-detect language: TS/JS/Python/Go)
+    getFileStructureTool,
+    getComplexityTool,
+    // DB tools (project, workitem, document, plan, backlog, anchor, artifact, episode)
+    ...allDbTools,
+    // Delegation status (coordinator query)
+    delegationStatusTool,
+];
+// =============================================================================
+// LEGACY API (for backwards compatibility)
+// =============================================================================
 /**
  * Creates the tool registry with all available tools.
  * Returns tools as-is - the Agent.registerTools() method handles typing.
+ *
+ * @deprecated Use createDirectToolRegistry() + initializeMetaTools() instead
  */
 export function createToolRegistry() {
     return [
-        // Built-in tools from @compilr-dev/agents
-        readFileTool,
-        writeFileTool,
-        bashTool,
-        bashOutputTool, // Monitor background processes
-        killShellTool, // Terminate background processes
-        grepTool,
-        globTool,
-        editTool,
-        todoWriteTool,
-        todoReadTool,
-        // Coding tools from @compilr-dev/agents-coding
-        gitStatusTool,
-        gitDiffTool,
-        gitLogTool,
-        gitCommitTool,
-        gitBranchTool,
-        detectProjectTool,
-        findProjectRootTool,
-        runTestsTool,
-        runLintTool,
-        // Local tools
-        backlogReadTool,
-        backlogWriteTool,
-        askUserTool,
-        askUserSimpleTool,
+        ...DIRECT_TOOLS,
+        ...META_REGISTRY_TOOLS,
     ];
 }
 /**
@@ -119,3 +241,81 @@ export function createMinimalToolRegistry() {
         globTool,
     ];
 }
+// =============================================================================
+// META-TOOLS API (new architecture)
+// =============================================================================
+/**
+ * Get direct tools that are always available.
+ * These are declared normally and can be called by name.
+ */
+export function getDirectTools() {
+    return DIRECT_TOOLS;
+}
+/**
+ * Get meta-tools for agent registration.
+ * Only get_tool_info is kept as a direct tool — use_tool and list_tools
+ * are no longer needed since the fallback handler routes calls transparently.
+ */
+export function getMetaTools() {
+    return [getToolInfoTool];
+}
+/**
+ * Create a fallback handler for the tool registry.
+ * When the agent calls a tool not in the direct registry, this handler
+ * checks the meta-registry and executes it transparently.
+ */
+export function createToolFallback() {
+    return createMetaToolFallback();
+}
+/**
+ * Initialize the meta-tool registry with specialized tools.
+ * Call this once at startup.
+ */
+export function initializeMetaTools() {
+    initializeMetaToolRegistry(META_REGISTRY_TOOLS);
+}
+/**
+ * Get the tool index for the system prompt.
+ * This lists all meta-registry tools with their signatures.
+ */
+export function getToolIndexForSystemPrompt() {
+    return META_TOOLS_SYSTEM_PROMPT_PREFIX + generateToolIndex();
+}
+/**
+ * Get count of meta-registry tools.
+ */
+export function getMetaToolsCount() {
+    return getMetaToolCount();
+}
+/**
+ * Check if meta-tools mode is enabled.
+ * Returns true if the meta-tool registry has been initialized.
+ */
+export function isMetaToolsEnabled() {
+    return getMetaToolCount() > 0;
+}
+// =============================================================================
+// STATISTICS
+// =============================================================================
+/**
+ * Get tool statistics for debugging/display.
+ */
+export function getToolStats() {
+    const directCount = DIRECT_TOOLS.length;
+    const metaCount = META_REGISTRY_TOOLS.length;
+    const totalCount = directCount + metaCount;
+    // Rough estimates: ~300 tokens per tool definition
+    const tokensPerTool = 300;
+    const estimatedDirectTokens = directCount * tokensPerTool;
+    const estimatedMetaTokens = 800; // Tool index + meta-tool definitions
+    const estimatedLegacyTokens = totalCount * tokensPerTool;
+    return {
+        directTools: directCount,
+        metaRegistryTools: metaCount,
+        totalTools: totalCount,
+        estimatedDirectTokens,
+        estimatedMetaTokens,
+        estimatedLegacyTokens,
+        tokenSavings: estimatedLegacyTokens - estimatedDirectTokens - estimatedMetaTokens,
+    };
+}

package/dist/ui/ask-user-overlay.d.ts

@@ -1,8 +1,8 @@
 /**
- * Ask User Overlay
+ * Ask User Overlay (Refactored)
  *
  * Modal overlay for presenting multi-question forms to the user.
- * Used by the ask_user tool during /design and /refine workflows.
+ * Uses InlineOverlay base class for consistent lifecycle management.
  *
  * Features:
  * - Multiple questions with navigation (←/→ or Tab)