@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/multi-agent/tool-config.js

@@ -0,0 +1,661 @@
+/**
+ * Tool Configuration for Custom Agents
+ *
+ * Defines tool groups, profiles, and helpers for configuring
+ * which tools a custom agent can access.
+ *
+ * IMPORTANT: Tool names are imported from tool-names.ts (single source of truth).
+ * DO NOT hardcode tool name strings here - use TOOL_NAMES constants.
+ */
+import { TOOL_NAMES } from '../tool-names.js';
+// =============================================================================
+// Tool Groups
+// =============================================================================
+/**
+ * All tool groups organized by functionality.
+ * These cover all ~50 tools in the CLI.
+ *
+ * Tool names use TOOL_NAMES constants for consistency.
+ */
+export const TOOL_GROUPS = {
+    // ============= DIRECT TOOLS (15) =============
+    file_read: {
+        label: 'File Reading',
+        tools: [TOOL_NAMES.READ_FILE, TOOL_NAMES.GLOB, TOOL_NAMES.GREP],
+        readOnly: true,
+        tier: 'direct',
+    },
+    file_write: {
+        label: 'File Writing',
+        tools: [TOOL_NAMES.WRITE_FILE, TOOL_NAMES.EDIT],
+        readOnly: false,
+        tier: 'direct',
+    },
+    shell: {
+        label: 'Shell Commands',
+        tools: [TOOL_NAMES.BASH, TOOL_NAMES.BASH_OUTPUT, TOOL_NAMES.KILL_SHELL],
+        readOnly: false,
+        tier: 'direct',
+    },
+    tasks: {
+        label: 'Task Tracking',
+        tools: [TOOL_NAMES.TODO_WRITE, TOOL_NAMES.TODO_READ, TOOL_NAMES.TODO_CLAIM, TOOL_NAMES.TODO_HANDOFF],
+        readOnly: false,
+        tier: 'direct',
+    },
+    interaction: {
+        label: 'User Interaction',
+        tools: [TOOL_NAMES.ASK_USER, TOOL_NAMES.ASK_USER_SIMPLE, TOOL_NAMES.SUGGEST],
+        readOnly: true,
+        tier: 'direct',
+    },
+    coordinator: {
+        label: 'Coordination',
+        tools: [TOOL_NAMES.DELEGATE, TOOL_NAMES.DELEGATE_BACKGROUND, TOOL_NAMES.DELEGATION_STATUS],
+        readOnly: false,
+        tier: 'direct',
+        note: 'Coordinator-only: delegation to specialists (foreground, background, status query)',
+    },
+    handoff: {
+        label: 'Agent Handoff',
+        tools: [TOOL_NAMES.HANDOFF],
+        readOnly: false,
+        tier: 'direct',
+        note: 'Hand off current task to another specialist or coordinator',
+    },
+    guide: {
+        label: 'CLI Documentation',
+        tools: [TOOL_NAMES.COMPILR_GUIDE],
+        readOnly: true,
+        tier: 'direct',
+        note: 'Always available: helps agents answer CLI questions',
+    },
+    meta: {
+        label: 'Tool Discovery',
+        tools: [TOOL_NAMES.LIST_TOOLS, TOOL_NAMES.GET_TOOL_INFO, TOOL_NAMES.USE_TOOL],
+        readOnly: true, // Meta-tools themselves are read-only
+        tier: 'direct',
+        note: 'Required for accessing meta-registry tools',
+    },
+    // ============= META-REGISTRY TOOLS (34+) =============
+    // Accessed via use_tool("name", args)
+    git_read: {
+        label: 'Git (Read)',
+        tools: [
+            TOOL_NAMES.GIT_STATUS,
+            TOOL_NAMES.GIT_DIFF,
+            TOOL_NAMES.GIT_LOG,
+            TOOL_NAMES.GIT_BLAME,
+            TOOL_NAMES.GIT_FILE_HISTORY,
+        ],
+        readOnly: true,
+        tier: 'meta',
+    },
+    git_write: {
+        label: 'Git (Write)',
+        tools: [TOOL_NAMES.GIT_COMMIT, TOOL_NAMES.GIT_BRANCH, TOOL_NAMES.GIT_STASH],
+        readOnly: false,
+        tier: 'meta',
+    },
+    project: {
+        label: 'Project Analysis',
+        tools: [
+            TOOL_NAMES.DETECT_PROJECT,
+            TOOL_NAMES.FIND_PROJECT_ROOT,
+            TOOL_NAMES.GET_FILE_STRUCTURE,
+            TOOL_NAMES.GET_COMPLEXITY,
+            TOOL_NAMES.READ_FUNCTION,
+            TOOL_NAMES.READ_CLASS,
+            TOOL_NAMES.READ_TYPE,
+        ],
+        readOnly: true,
+        tier: 'meta',
+        note: 'Includes smart file reading (read_function, read_class, read_type)',
+    },
+    runners: {
+        label: 'Runners (Test/Build/Lint)',
+        tools: [TOOL_NAMES.RUN_TESTS, TOOL_NAMES.RUN_LINT, TOOL_NAMES.RUN_BUILD, TOOL_NAMES.RUN_FORMAT],
+        readOnly: false, // Can have side effects
+        tier: 'meta',
+    },
+    search: {
+        label: 'Code Search',
+        tools: [TOOL_NAMES.FIND_DEFINITION, TOOL_NAMES.FIND_REFERENCES, TOOL_NAMES.FIND_TODOS],
+        readOnly: true,
+        tier: 'meta',
+    },
+    dependencies: {
+        label: 'Dependency Analysis',
+        tools: [
+            TOOL_NAMES.CHECK_OUTDATED,
+            TOOL_NAMES.FIND_VULNERABILITIES,
+            TOOL_NAMES.ANALYZE_TEST_COVERAGE,
+        ],
+        readOnly: true,
+        tier: 'meta',
+    },
+    backlog_read: {
+        label: 'Backlog (Read)',
+        tools: [TOOL_NAMES.WORKITEM_QUERY, TOOL_NAMES.WORKITEM_STATUS_COUNTS],
+        readOnly: true,
+        tier: 'meta',
+    },
+    backlog_write: {
+        label: 'Backlog (Write)',
+        tools: [
+            TOOL_NAMES.WORKITEM_ADD,
+            TOOL_NAMES.WORKITEM_UPDATE,
+            TOOL_NAMES.WORKITEM_DELETE,
+            TOOL_NAMES.WORKITEM_NEXT,
+            TOOL_NAMES.WORKITEM_ADVANCE_STEP,
+            TOOL_NAMES.WORKITEM_CLAIM,
+            TOOL_NAMES.WORKITEM_HANDOFF,
+        ],
+        readOnly: false,
+        tier: 'meta',
+    },
+    documents: {
+        label: 'Project Documents',
+        tools: [
+            TOOL_NAMES.PROJECT_DOCUMENT_ADD,
+            TOOL_NAMES.PROJECT_DOCUMENT_GET,
+            TOOL_NAMES.PROJECT_DOCUMENT_LIST,
+            TOOL_NAMES.PROJECT_DOCUMENT_DELETE,
+        ],
+        readOnly: false,
+        tier: 'meta',
+    },
+    plans: {
+        label: 'Planning',
+        tools: [
+            TOOL_NAMES.PLAN_CREATE,
+            TOOL_NAMES.PLAN_UPDATE,
+            TOOL_NAMES.PLAN_GET,
+            TOOL_NAMES.PLAN_LIST,
+            TOOL_NAMES.PLAN_DELETE,
+        ],
+        readOnly: false,
+        tier: 'meta',
+    },
+    artifacts: {
+        label: 'Team Artifacts',
+        tools: [
+            TOOL_NAMES.ARTIFACT_SAVE,
+            TOOL_NAMES.ARTIFACT_GET,
+            TOOL_NAMES.ARTIFACT_LIST,
+            TOOL_NAMES.ARTIFACT_DELETE,
+        ],
+        readOnly: false,
+        tier: 'meta',
+    },
+    anchors: {
+        label: 'Context Anchors',
+        tools: [TOOL_NAMES.ANCHOR_ADD, TOOL_NAMES.ANCHOR_LIST, TOOL_NAMES.ANCHOR_REMOVE],
+        readOnly: false,
+        tier: 'meta',
+    },
+    project_db: {
+        label: 'Project Database',
+        tools: [TOOL_NAMES.PROJECT_GET, TOOL_NAMES.PROJECT_LIST, TOOL_NAMES.PROJECT_UPDATE],
+        readOnly: false,
+        tier: 'meta',
+        note: 'Project metadata management',
+    },
+    subagents: {
+        label: 'Subagent Delegation',
+        tools: [TOOL_NAMES.TASK],
+        readOnly: false,
+        tier: 'direct',
+        note: 'Delegate tasks to specialized subagents',
+    },
+};
+// =============================================================================
+// Tool Profiles
+// =============================================================================
+/**
+ * Predefined tool profiles mapping profile name to included groups.
+ */
+export const TOOL_PROFILES = {
+    // Full access - all groups
+    full: Object.keys(TOOL_GROUPS),
+    // Read-only - safe exploration
+    'read-only': [
+        'file_read',
+        'interaction',
+        'guide',
+        'meta',
+        'git_read',
+        'project',
+        'search',
+        'dependencies',
+        'backlog_read',
+    ],
+    // Developer - coding tasks
+    developer: [
+        'file_read',
+        'file_write',
+        'shell',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'subagents',
+        'meta',
+        'git_read',
+        'git_write',
+        'project',
+        'project_db',
+        'runners',
+        'search',
+        'backlog_read',
+        'backlog_write',
+        'documents',
+        'plans',
+        'artifacts',
+        'anchors',
+    ],
+    // Security - security audits
+    security: [
+        'file_read',
+        'shell',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'git_read',
+        'project',
+        'search',
+        'dependencies',
+    ],
+    // Docs - documentation only
+    docs: [
+        'file_read',
+        'file_write',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'project',
+        'search',
+    ],
+    // DevOps - CI/CD tasks
+    devops: [
+        'file_read',
+        'file_write',
+        'shell',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'git_read',
+        'git_write',
+        'project',
+        'project_db',
+        'runners',
+        'dependencies',
+    ],
+    // QA - testing
+    qa: [
+        'file_read',
+        'shell',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'git_read',
+        'project',
+        'runners',
+        'search',
+        'dependencies',
+    ],
+    // Architect - design and analysis (no direct implementation)
+    architect: [
+        'file_read',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'git_read',
+        'project',
+        'search',
+        'dependencies',
+        'backlog_read',
+        'documents',
+        'plans',
+        'artifacts',
+        'anchors',
+    ],
+    // Planner (PM) - project management (no code modification)
+    planner: [
+        'file_read',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'git_read',
+        'project',
+        'project_db',
+        'backlog_read',
+        'backlog_write',
+        'documents',
+        'plans',
+        'artifacts',
+        'anchors',
+    ],
+    // Analyst (BA) - requirements gathering (minimal technical tools)
+    analyst: [
+        'file_read',
+        'tasks',
+        'interaction',
+        'handoff',
+        'guide',
+        'meta',
+        'project',
+        'backlog_read',
+        'backlog_write',
+        'documents',
+        'artifacts',
+        'anchors',
+    ],
+    // Custom - user selected (groups specified in customGroups)
+    custom: [],
+};
+export const PROFILE_INFO = {
+    full: {
+        label: 'Full Access',
+        description: 'All tools available (default)',
+        isReadOnly: false,
+    },
+    'read-only': {
+        label: 'Read Only',
+        description: 'Safe exploration - no file writes or destructive ops',
+        isReadOnly: true,
+    },
+    developer: {
+        label: 'Developer',
+        description: 'Full coding capabilities without destructive git ops',
+        isReadOnly: false,
+    },
+    security: {
+        label: 'Security Reviewer',
+        description: 'Security audits - read files, run analysis tools',
+        isReadOnly: true,
+    },
+    docs: {
+        label: 'Documentation',
+        description: 'Read and write documentation files',
+        isReadOnly: false,
+    },
+    devops: {
+        label: 'DevOps',
+        description: 'CI/CD tasks - runners, git, shell',
+        isReadOnly: false,
+    },
+    qa: {
+        label: 'QA / Testing',
+        description: 'Testing tasks - read code, run tests, analyze coverage',
+        isReadOnly: true,
+    },
+    architect: {
+        label: 'Architect',
+        description: 'Design and analysis - read code, create artifacts, no direct edits',
+        isReadOnly: true,
+    },
+    planner: {
+        label: 'Planner',
+        description: 'Project management - backlog, documents, no code modification',
+        isReadOnly: true,
+    },
+    analyst: {
+        label: 'Analyst',
+        description: 'Requirements gathering - user stories, documents, business analysis',
+        isReadOnly: true,
+    },
+    custom: {
+        label: 'Custom',
+        description: 'Select tool groups manually',
+        isReadOnly: false,
+    },
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get all tool names for a given profile.
+ *
+ * @param profile - The tool profile
+ * @param customGroups - Custom groups (when profile is 'custom')
+ * @returns Array of tool names
+ */
+export function getToolsForProfile(profile, customGroups) {
+    const groups = profile === 'custom'
+        ? (customGroups ?? [])
+        : TOOL_PROFILES[profile];
+    const tools = [];
+    for (const groupId of groups) {
+        if (groupId in TOOL_GROUPS) {
+            tools.push(...TOOL_GROUPS[groupId].tools);
+        }
+    }
+    return [...new Set(tools)]; // Deduplicate
+}
+/**
+ * Get all group IDs for a profile.
+ */
+export function getGroupsForProfile(profile) {
+    return TOOL_PROFILES[profile];
+}
+/**
+ * Get the profile that best matches a set of tools.
+ * Used for displaying current config in UI.
+ */
+export function detectProfileFromTools(tools) {
+    const toolSet = new Set(tools);
+    const allTools = getToolsForProfile('full');
+    // Full access if all tools included
+    if (allTools.every(t => toolSet.has(t))) {
+        return 'full';
+    }
+    // Check each profile
+    for (const profile of Object.keys(TOOL_PROFILES)) {
+        if (profile === 'full' || profile === 'custom')
+            continue;
+        const profileTools = getToolsForProfile(profile);
+        if (profileTools.length === tools.length &&
+            profileTools.every(t => toolSet.has(t))) {
+            return profile;
+        }
+    }
+    return 'custom';
+}
+/**
+ * Check if a profile only includes read-only groups.
+ */
+export function isProfileReadOnly(profile, customGroups) {
+    const groups = profile === 'custom'
+        ? (customGroups ?? [])
+        : TOOL_PROFILES[profile];
+    return groups.every(groupId => {
+        if (!(groupId in TOOL_GROUPS)) {
+            return true; // Unknown group treated as read-only
+        }
+        return TOOL_GROUPS[groupId].readOnly;
+    });
+}
+/**
+ * Get all available group IDs.
+ */
+export function getAllGroupIds() {
+    return Object.keys(TOOL_GROUPS);
+}
+/**
+ * Get group info by ID.
+ */
+export function getGroupInfo(groupId) {
+    return TOOL_GROUPS[groupId];
+}
+/**
+ * Get groups organized by tier.
+ */
+export function getGroupsByTier() {
+    const direct = [];
+    const meta = [];
+    for (const [id, group] of Object.entries(TOOL_GROUPS)) {
+        if (group.tier === 'direct') {
+            direct.push(id);
+        }
+        else {
+            meta.push(id);
+        }
+    }
+    return { direct, meta };
+}
+/**
+ * Create a default tool config (full access).
+ */
+export function createDefaultToolConfig() {
+    return {
+        profile: 'full',
+    };
+}
+/**
+ * Validate a tool config.
+ */
+export function validateToolConfig(config) {
+    if (!config.profile) {
+        return { valid: false, error: 'Profile is required' };
+    }
+    if (!(config.profile in TOOL_PROFILES)) {
+        return { valid: false, error: `Unknown profile: ${config.profile}` };
+    }
+    if (config.profile === 'custom' && (!config.customGroups || config.customGroups.length === 0)) {
+        return { valid: false, error: 'Custom profile requires at least one group' };
+    }
+    if (config.customGroups) {
+        for (const groupId of config.customGroups) {
+            if (!(groupId in TOOL_GROUPS)) {
+                return { valid: false, error: `Unknown group: ${groupId}` };
+            }
+        }
+    }
+    return { valid: true };
+}
+/**
+ * Generate self-awareness text for system prompt.
+ * Tells the agent about its tool limitations.
+ */
+export function generateToolAwarenessPrompt(config) {
+    const profile = config.profile;
+    const profileInfo = PROFILE_INFO[profile];
+    const groups = profile === 'custom'
+        ? (config.customGroups ?? [])
+        : TOOL_PROFILES[profile];
+    const isReadOnly = config.readOnly || isProfileReadOnly(profile, config.customGroups);
+    const lines = [
+        '## Your Capabilities',
+        '',
+        `You are configured with the "${profileInfo.label}" tool profile.`,
+        `Available tool groups: ${groups.join(', ')}`,
+        '',
+    ];
+    if (isReadOnly) {
+        lines.push('**You have READ-ONLY access.** You cannot modify files directly.');
+        lines.push('');
+    }
+    // Add specific limitations based on profile
+    const allGroups = getAllGroupIds();
+    const missingGroups = allGroups.filter(g => !groups.includes(g));
+    if (missingGroups.length > 0 && missingGroups.length < allGroups.length / 2) {
+        lines.push('## Tool Limitations');
+        lines.push('');
+        lines.push('The following capabilities are NOT available to you:');
+        for (const groupId of missingGroups) {
+            // groupId is guaranteed to exist (from getAllGroupIds)
+            const group = TOOL_GROUPS[groupId];
+            lines.push(`- ${group.label}: ${group.tools.join(', ')}`);
+        }
+        lines.push('');
+    }
+    lines.push('## When You Cannot Help');
+    lines.push('');
+    lines.push('If a user requests something outside your capabilities:');
+    lines.push('1. Acknowledge what they want to do');
+    lines.push('2. Explain your tool limitations');
+    lines.push('3. Suggest which team agent can help (e.g., "Try $dev for code modifications")');
+    return lines.join('\n');
+}
+/**
+ * Generate delegation guidance for the coordinator.
+ * Explains how to use the delegate tool effectively.
+ */
+export function generateCoordinatorGuidance() {
+    return `## Task Delegation
+
+As the coordinator, you have two delegation tools:
+
+### \`delegate\` (Foreground)
+Switches the active agent to a specialist. The user interacts directly with the specialist.
+- Use when the user should work directly with the specialist
+- Requires user approval before switching
+
+### \`delegate_background\` (Background — Coordinator Mode)
+Runs a specialist in background while you stay in the foreground.
+- Use when orchestrating multiple tasks across specialists
+- Specialists work independently; you're notified on completion
+- Can delegate to multiple specialists in parallel
+- Associate delegations with todos via \`todoIndex\` for plan tracking
+
+### Choosing the Right Specialist
+Look at the **Your Team** roster in the shared context above. Each agent has:
+- A **role** (e.g., Developer, Architect, QA)
+- An **expertise** list (e.g., "system design, API design")
+
+Match the task to the agent whose expertise best fits. For example:
+- Architecture/design tasks → agent with design/architecture expertise
+- Implementation/coding → agent with development/debugging expertise
+- Testing/quality review → agent with testing/QA expertise
+- Planning/requirements → agent with planning/coordination expertise
+
+If no specialist matches well, handle the task yourself rather than delegating poorly.
+
+### Todo Ownership
+When creating todos (via todo_write), ALWAYS assign an owner:
+- Use your own agent ID ("default") for tasks you will handle yourself
+- Use the specialist's agent ID for tasks you plan to delegate to them
+- Never leave todos unassigned — unassigned todos confuse specialists who may try to work on them
+
+### Guidelines
+- Break complex tasks into clear, independent sub-tasks
+- Delegate sub-tasks to the most appropriate specialist based on their expertise
+- Each delegation should have a clear expected output
+- For sequential work, wait for completion before chaining the next delegation
+- For parallel work, delegate multiple tasks simultaneously`;
+}
+/**
+ * Generate delegation suggestion guidance for specialists.
+ * Explains how to suggest other specialists when appropriate.
+ */
+export function generateSpecialistGuidance(role) {
+    return `## Collaborating with Team
+
+You are a specialist focused on ${role}-related tasks.
+
+When a request is outside your expertise or could benefit from another specialist:
+1. Use the \`handoff\` tool to transfer the task to the right specialist
+2. Provide a clear task description and reason for the handoff
+3. The user will be asked to approve the handoff before switching
+
+Examples:
+- Architecture questions → handoff to $arch
+- Implementation tasks → handoff to $dev
+- Testing strategy → handoff to $qa
+
+Note: If you were handed this task by another agent, you cannot re-hand it off
+(except back to the coordinator). Complete the task or return it.
+
+Focus on what you do best - don't try to do everything yourself.`;
+}