@claudetools/tools 0.3.9 → 0.4.0

package/dist/handlers/tool-handlers.js

@@ -3,13 +3,16 @@
 // =============================================================================
 import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { mcpLogger } from '../logger.js';
-import { getDefaultProjectId, DEFAULT_USER_ID, lastContextUsed, setLastContextUsed } from '../helpers/config.js';
+import { getDefaultProjectId, DEFAULT_USER_ID, lastContextUsed, setLastContextUsed, API_BASE_URL } from '../helpers/config.js';
 import { EXPERT_WORKERS, matchTaskToWorker } from '../helpers/workers.js';
-import { searchMemory, addMemory, storeFact, getContext, getSummary, getEntities, injectContext, apiRequest } from '../helpers/api-client.js';
+import { searchMemory, addMemory, storeFact, getContext, getSummary, getEntities, injectContext, apiRequest, listCachedDocs, getCachedDocs, cacheDocs } from '../helpers/api-client.js';
 import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
 import { checkPatterns } from '../helpers/patterns.js';
 import { formatContextForClaude } from '../helpers/formatter.js';
-import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, } from '../helpers/tasks.js';
+import { createTask, listTasks, getTask, claimTask, releaseTask, updateTaskStatus, addTaskContext, getTaskSummary, heartbeatTask, parseJsonArray, getDispatchableTasks, getExecutionContext, resolveTaskDependencies, getEpicStatus, getActiveTaskCount, } from '../helpers/tasks.js';
+import { detectTimedOutTasks, retryTask, failTask, autoRetryTimedOutTasks, } from '../helpers/tasks-retry.js';
+import { detectLibrariesFromPlan } from '../helpers/library-detection.js';
+import { handleGenerateApi, handleGenerateFrontend, handleGenerateComponent, handleListGenerators, handleValidateSpec, } from './codedna-handlers.js';
 export function registerToolHandlers(server) {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
@@ -344,6 +347,20 @@ export function registerToolHandlers(server) {
                     const risks = args?.risks;
                     const questions = args?.questions;
                     const priority = args?.priority || 'medium';
+                    // Detect libraries mentioned in the plan
+                    const detectedLibraries = detectLibrariesFromPlan(goal, tasks);
+                    // Check docs cache for each detected library
+                    const cachedDocsStatus = [];
+                    const cachedDocsList = await listCachedDocs(projectId);
+                    const cachedLibraryIds = new Set(cachedDocsList.libraries.map(l => l.library_id));
+                    for (const lib of detectedLibraries) {
+                        const isCached = lib.context7Id ? cachedLibraryIds.has(lib.context7Id) : false;
+                        cachedDocsStatus.push({
+                            name: lib.name,
+                            cached: isCached,
+                            context7Id: lib.context7Id,
+                        });
+                    }
                     mcpLogger.toolResult(name, true, timer());
                     let output = `## Plan: ${epicTitle}\n\n`;
                     output += `**Goal:** ${goal}\n\n`;
@@ -353,6 +370,27 @@ export function registerToolHandlers(server) {
                     if (approach) {
                         output += `**Approach:** ${approach}\n\n`;
                     }
+                    // Show detected libraries with cache status
+                    if (cachedDocsStatus.length > 0) {
+                        const needsFetch = cachedDocsStatus.filter(l => !l.cached && l.context7Id);
+                        const alreadyCached = cachedDocsStatus.filter(l => l.cached);
+                        const noDocsAvailable = cachedDocsStatus.filter(l => !l.context7Id);
+                        output += `### Documentation Status\n\n`;
+                        if (alreadyCached.length > 0) {
+                            output += `**Cached:** ${alreadyCached.map(l => l.name).join(', ')}\n`;
+                        }
+                        if (needsFetch.length > 0) {
+                            output += `**Needs fetching:** ${needsFetch.map(l => l.name).join(', ')}\n`;
+                            output += `\n> **Action Required:** Fetch docs from context7, then cache them:\n`;
+                            output += `> 1. Use \`resolve-library-id\` and \`get-library-docs\` for each: ${needsFetch.map(l => `\`${l.context7Id}\``).join(', ')}\n`;
+                            output += `> 2. Cache each with \`docs_cache(library_id, library_name, content)\`\n`;
+                            output += `> 3. Then approve the plan to create tasks with docs attached\n`;
+                        }
+                        if (noDocsAvailable.length > 0) {
+                            output += `**No docs available:** ${noDocsAvailable.map(l => l.name).join(', ')}\n`;
+                        }
+                        output += '\n';
+                    }
                     output += `### Tasks\n\n`;
                     tasks.forEach((t, i) => {
                         const effort = t.effort ? ` (${t.effort})` : '';
@@ -412,9 +450,63 @@ export function registerToolHandlers(server) {
                             agent_type: worker.id,
                             domain: taskDef.domain,
                         });
-                        createdTasks.push({ task: taskResult.data, worker });
+                        const taskId = taskResult.data.id;
+                        let contextCount = 0;
+                        // Search memory for relevant patterns/facts
+                        const searchQuery = `${taskDef.title} ${taskDef.description || ''}`;
+                        try {
+                            const memoryResults = await searchMemory(projectId, searchQuery, 5);
+                            // Attach relevant facts as context
+                            if (memoryResults.relevant_facts?.length > 0) {
+                                const factsContent = memoryResults.relevant_facts
+                                    .slice(0, 3) // Limit to top 3 facts
+                                    .map(f => `- ${f.fact}`)
+                                    .join('\n');
+                                await addTaskContext(DEFAULT_USER_ID, projectId, taskId, 'pattern', factsContent, 'task_plan', 'memory:facts');
+                                contextCount += memoryResults.relevant_facts.slice(0, 3).length;
+                            }
+                            // Attach relevant entities as context
+                            if (memoryResults.relevant_entities?.length > 0) {
+                                const entitiesContent = memoryResults.relevant_entities
+                                    .slice(0, 3)
+                                    .map(e => `- **${e.name}** (${e.labels.join(', ')})${e.summary ? `: ${e.summary}` : ''}`)
+                                    .join('\n');
+                                await addTaskContext(DEFAULT_USER_ID, projectId, taskId, 'reference', entitiesContent, 'task_plan', 'memory:entities');
+                                contextCount += memoryResults.relevant_entities.slice(0, 3).length;
+                            }
+                        }
+                        catch {
+                            // Memory search failed, continue without context
+                            mcpLogger.warn('TOOL', `Memory search failed for task: ${taskDef.title}`);
+                        }
+                        // Attach cached documentation for detected libraries
+                        try {
+                            const taskLibraries = detectLibrariesFromPlan(`${taskDef.title} ${taskDef.description || ''}`, [{ title: taskDef.title, description: taskDef.description }]);
+                            for (const lib of taskLibraries) {
+                                if (lib.context7Id) {
+                                    const cachedDoc = await getCachedDocs(projectId, lib.context7Id);
+                                    if (cachedDoc && cachedDoc.content) {
+                                        // Truncate to reasonable size for task context (first 2000 chars)
+                                        const truncatedContent = cachedDoc.content.length > 2000
+                                            ? cachedDoc.content.slice(0, 2000) + '\n\n... (truncated, use docs_get for full content)'
+                                            : cachedDoc.content;
+                                        await addTaskContext(DEFAULT_USER_ID, projectId, taskId, 'reference', `## ${lib.name} Documentation\n\n${truncatedContent}`, 'task_plan', `docs:${lib.context7Id}`);
+                                        contextCount++;
+                                    }
+                                }
+                            }
+                        }
+                        catch {
+                            mcpLogger.warn('TOOL', `Docs attachment failed for task: ${taskDef.title}`);
+                        }
+                        // Immediately set task to 'ready' status for auto-dispatch
+                        await updateTaskStatus(DEFAULT_USER_ID, projectId, taskId, 'ready');
+                        taskResult.data.status = 'ready'; // Update local copy
+                        createdTasks.push({ task: taskResult.data, worker, contextCount });
                     }
                     mcpLogger.toolResult(name, true, timer());
+                    // Get dispatchable tasks with full execution context
+                    const dispatchable = await getDispatchableTasks(DEFAULT_USER_ID, projectId, epic.id, createdTasks.length);
                     // Group tasks by worker for parallel dispatch overview
                     const byWorker = new Map();
                     for (const item of createdTasks) {
@@ -422,16 +514,22 @@ export function registerToolHandlers(server) {
                         existing.push(item);
                         byWorker.set(item.worker.id, existing);
                     }
-                    let output = `# Work Plan Created\n\n`;
+                    // Calculate total context injected
+                    const totalContext = createdTasks.reduce((sum, t) => sum + t.contextCount, 0);
+                    let output = `# Work Plan Created & Ready for Dispatch\n\n`;
                     output += `## Epic: ${epic.title}\n`;
                     output += `**ID:** \`${epic.id}\`\n`;
-                    output += `**Priority:** ${priority}\n\n`;
+                    output += `**Priority:** ${priority}\n`;
+                    output += `**Status:** All tasks set to \`ready\`\n`;
+                    output += `**Context Injected:** ${totalContext} items from memory\n\n`;
                     output += `**Goal:** ${goal}\n\n`;
                     output += `## Tasks (${createdTasks.length})\n\n`;
                     createdTasks.forEach((item, i) => {
                         output += `${i + 1}. **${item.task.title}**\n`;
                         output += `   - ID: \`${item.task.id}\`\n`;
                         output += `   - Worker: ${item.worker.name} (\`${item.worker.id}\`)\n`;
+                        output += `   - Status: \`ready\`\n`;
+                        output += `   - Context: ${item.contextCount} items\n`;
                         if (item.task.estimated_effort)
                             output += `   - Effort: ${item.task.estimated_effort}\n`;
                         if (item.task.description)
@@ -443,11 +541,25 @@ export function registerToolHandlers(server) {
                         const worker = EXPERT_WORKERS[workerId];
                         output += `- **${worker.name}**: ${items.length} task(s)\n`;
                     }
+                    // Auto-dispatch section with exact Task tool invocations
                     output += `\n---\n\n`;
-                    output += `## Execution Options\n\n`;
-                    output += `**Sequential:** Use \`task_start\` with each task ID.\n\n`;
-                    output += `**Parallel:** Use \`task_dispatch\` to spawn workers:\n`;
-                    output += `\`\`\`\ntask_dispatch(epic_id="${epic.id}")\n\`\`\`\n`;
+                    output += `## Auto-Dispatch: Spawn Parallel Agents Now\n\n`;
+                    output += `**IMPORTANT:** Execute these Task tool calls in a SINGLE message to spawn parallel workers:\n\n`;
+                    output += `\`\`\`\n`;
+                    for (const dt of dispatchable) {
+                        // Build a concise but complete prompt for the agent
+                        const taskPrompt = [
+                            `Execute task ${dt.task.id}: ${dt.task.title}`,
+                            dt.task.description ? `\nDescription: ${dt.task.description}` : '',
+                            `\nEpic: ${epic.title}`,
+                            `\nGoal: ${goal}`,
+                            `\nWhen complete, call task_complete(task_id="${dt.task.id}", summary="...") with a summary of work done.`,
+                        ].filter(Boolean).join('');
+                        output += `Task(subagent_type="general-purpose", prompt="${taskPrompt.replace(/"/g, '\\"')}")\n`;
+                    }
+                    output += `\`\`\`\n\n`;
+                    output += `**Note:** All ${dispatchable.length} tasks are ready for parallel execution. `;
+                    output += `Each agent will claim its task, execute, and report completion.\n`;
                     return {
                         content: [{ type: 'text', text: output }],
                     };
@@ -927,13 +1039,349 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                case 'task_epic_status': {
+                    const epicId = args?.epic_id;
+                    const status = await getEpicStatus(DEFAULT_USER_ID, projectId, epicId);
+                    mcpLogger.toolResult(name, true, timer());
+                    const statusEmoji = {
+                        backlog: '📋', ready: '🟢', in_progress: '🔄',
+                        blocked: '🚫', review: '👀', done: '✅', cancelled: '❌'
+                    };
+                    let output = `# Epic Progress: ${status.epic.title}\n\n`;
+                    output += `**Epic ID:** \`${epicId}\`\n`;
+                    output += `**Epic Status:** ${status.epic.status}`;
+                    if (status.autoCompleted) {
+                        output += ` ✨ (auto-completed)`;
+                    }
+                    output += `\n`;
+                    output += `**Total Tasks:** ${status.totalTasks}\n`;
+                    output += `**Progress:** ${status.percentComplete}% complete\n`;
+                    output += `**All Complete:** ${status.allComplete ? '✅ Yes' : '❌ No'}\n\n`;
+                    output += `## Task Breakdown\n\n`;
+                    if (status.totalTasks === 0) {
+                        output += `No child tasks found for this epic.\n`;
+                    }
+                    else {
+                        output += `| Status | Count | Percentage |\n`;
+                        output += `|--------|-------|------------|\n`;
+                        for (const [statusKey, count] of Object.entries(status.byStatus)) {
+                            if (count > 0) {
+                                const emoji = statusEmoji[statusKey] || '📝';
+                                const percentage = Math.round((count / status.totalTasks) * 100);
+                                output += `| ${emoji} ${statusKey} | ${count} | ${percentage}% |\n`;
+                            }
+                        }
+                        output += `\n`;
+                        // Progress bar visualization
+                        const doneCount = status.byStatus.done || 0;
+                        const progressBar = '█'.repeat(Math.floor(status.percentComplete / 5)) +
+                            '░'.repeat(20 - Math.floor(status.percentComplete / 5));
+                        output += `**Progress Bar:** [${progressBar}] ${status.percentComplete}%\n\n`;
+                        // Summary
+                        if (status.allComplete) {
+                            output += `🎉 **All tasks completed!** Epic ${status.autoCompleted ? 'has been automatically marked as done' : 'is complete'}.`;
+                        }
+                        else {
+                            const remaining = status.totalTasks - doneCount;
+                            output += `📊 **${remaining} task(s) remaining** to complete this epic.`;
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_detect_timeouts': {
+                    const timedOut = await detectTimedOutTasks(DEFAULT_USER_ID, projectId);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Timed-Out Tasks\n\n`;
+                    output += `Found ${timedOut.length} task(s) with expired locks.\n\n`;
+                    if (timedOut.length === 0) {
+                        output += `No timed-out tasks detected. All in-progress tasks have valid locks.\n`;
+                    }
+                    else {
+                        for (const { task, lockExpiredAt, timeSinceExpiry } of timedOut) {
+                            const minutesAgo = Math.floor(timeSinceExpiry / 1000 / 60);
+                            output += `## ${task.title}\n`;
+                            output += `- **Task ID:** \`${task.id}\`\n`;
+                            output += `- **Status:** ${task.status}\n`;
+                            output += `- **Assigned to:** ${task.assigned_to || 'None'}\n`;
+                            output += `- **Lock expired:** ${lockExpiredAt} (${minutesAgo} minutes ago)\n`;
+                            output += `- **Parent:** ${task.parent_id || 'None'}\n\n`;
+                        }
+                        output += `---\n\n`;
+                        output += `**Next Steps:**\n`;
+                        output += `- Use \`task_retry\` to retry individual tasks\n`;
+                        output += `- Use \`task_auto_retry_timeouts\` to automatically handle all timed-out tasks\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_retry': {
+                    const taskId = args?.task_id;
+                    const maxRetries = args?.max_retries || 3;
+                    const errorContext = args?.error_context;
+                    const result = await retryTask(DEFAULT_USER_ID, projectId, taskId, maxRetries, errorContext);
+                    mcpLogger.toolResult(name, result.success, timer());
+                    let output = '';
+                    if (result.success && result.data) {
+                        const { task, retryCount, retriesRemaining } = result.data;
+                        output = `# Task Retry Successful\n\n`;
+                        output += `**Task:** ${task.title}\n`;
+                        output += `**Task ID:** \`${taskId}\`\n`;
+                        output += `**New Status:** ${task.status} (reset to ready)\n`;
+                        output += `**Retry Count:** ${retryCount}/${maxRetries}\n`;
+                        output += `**Retries Remaining:** ${retriesRemaining}\n\n`;
+                        output += `The task has been reset and is ready to be claimed again.\n\n`;
+                        if (errorContext) {
+                            output += `**Previous Failure:** ${errorContext}\n`;
+                        }
+                    }
+                    else {
+                        output = `# Task Retry Failed\n\n`;
+                        output += `**Task ID:** \`${taskId}\`\n`;
+                        output += `**Error:** ${result.error}\n\n`;
+                        if (result.error?.includes('Retry limit exceeded')) {
+                            output += `The task has been marked as **failed** permanently.\n`;
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_fail': {
+                    const taskId = args?.task_id;
+                    const errorContext = args?.error_context;
+                    const agentId = args?.agent_id;
+                    const result = await failTask(DEFAULT_USER_ID, projectId, taskId, errorContext, agentId);
+                    mcpLogger.toolResult(name, result.success, timer());
+                    let output = `# Task Marked as Failed\n\n`;
+                    output += `**Task:** ${result.data.title}\n`;
+                    output += `**Task ID:** \`${taskId}\`\n`;
+                    output += `**Status:** failed\n`;
+                    output += `**Error:** ${errorContext}\n\n`;
+                    output += `The task has been marked as failed and the error context has been logged.\n`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_auto_retry_timeouts': {
+                    const maxRetries = args?.max_retries || 3;
+                    const result = await autoRetryTimedOutTasks(DEFAULT_USER_ID, projectId, maxRetries);
+                    mcpLogger.toolResult(name, true, timer());
+                    let output = `# Auto-Retry Timed-Out Tasks\n\n`;
+                    output += `**Found:** ${result.timedOut.length} timed-out task(s)\n`;
+                    output += `**Retried:** ${result.retried.length} task(s)\n`;
+                    output += `**Failed Permanently:** ${result.failed.length} task(s)\n\n`;
+                    if (result.retried.length > 0) {
+                        output += `## Successfully Retried\n\n`;
+                        for (const task of result.retried) {
+                            output += `- **${task.title}** (\`${task.id}\`) - reset to ready\n`;
+                        }
+                        output += `\n`;
+                    }
+                    if (result.failed.length > 0) {
+                        output += `## Failed Permanently (Retry Limit Exceeded)\n\n`;
+                        for (const task of result.failed) {
+                            output += `- **${task.title}** (\`${task.id}\`) - marked as failed\n`;
+                        }
+                        output += `\n`;
+                    }
+                    if (result.timedOut.length === 0) {
+                        output += `No timed-out tasks found. All in-progress tasks have valid locks.\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'task_orchestrate': {
+                    const epicId = args?.epic_id;
+                    const maxParallel = args?.max_parallel || 5;
+                    const maxRetries = args?.max_retries || 3;
+                    const dryRun = args?.dry_run || false;
+                    // Get epic status
+                    const epicStatus = await getEpicStatus(DEFAULT_USER_ID, projectId, epicId);
+                    mcpLogger.toolResult(name, true, timer());
+                    // Get dispatchable tasks
+                    const dispatchable = await getDispatchableTasks(DEFAULT_USER_ID, projectId, epicId, maxParallel);
+                    // Get active task count
+                    const activeCount = await getActiveTaskCount(DEFAULT_USER_ID, projectId, epicId);
+                    // Get timed-out tasks
+                    const timedOut = await detectTimedOutTasks(DEFAULT_USER_ID, projectId);
+                    const epicTimedOut = timedOut.filter(t => t.task.parent_id === epicId);
+                    // Get blocked tasks
+                    const blockedResult = await listTasks(DEFAULT_USER_ID, projectId, {
+                        status: 'blocked',
+                        parent_id: epicId,
+                        limit: 50,
+                    });
+                    const blockedTasks = blockedResult.success ? blockedResult.data : [];
+                    // Get failed tasks
+                    const failedResult = await listTasks(DEFAULT_USER_ID, projectId, {
+                        status: 'failed',
+                        parent_id: epicId,
+                        limit: 50,
+                    });
+                    const failedTasks = failedResult.success ? failedResult.data : [];
+                    // Determine overall status
+                    let status;
+                    if (epicStatus.allComplete) {
+                        status = 'complete';
+                    }
+                    else if (failedTasks.length > 0 && dispatchable.length === 0 && activeCount.total === 0) {
+                        status = 'failed';
+                    }
+                    else if (dispatchable.length === 0 && activeCount.total === 0 && blockedTasks.length > 0) {
+                        status = 'blocked';
+                    }
+                    else if (activeCount.total > 0 || dispatchable.length > 0) {
+                        status = 'in_progress';
+                    }
+                    else {
+                        status = 'ready';
+                    }
+                    // Build response
+                    let output = `# Epic Orchestration Status\n\n`;
+                    output += `**Epic:** ${epicStatus.epic.title}\n`;
+                    output += `**Epic ID:** \`${epicId}\`\n`;
+                    output += `**Status:** ${status}\n`;
+                    output += `**Progress:** ${epicStatus.percentComplete}% (${epicStatus.byStatus.done || 0}/${epicStatus.totalTasks} tasks)\n`;
+                    output += `**Dry Run:** ${dryRun ? 'Yes (preview only)' : 'No'}\n\n`;
+                    // Task breakdown
+                    output += `## Task Breakdown\n\n`;
+                    output += `- ✅ **Done:** ${epicStatus.byStatus.done || 0}\n`;
+                    output += `- 🔄 **In Progress:** ${epicStatus.byStatus.in_progress || 0} (${activeCount.claimed} actively claimed)\n`;
+                    output += `- 🟢 **Ready/Dispatchable:** ${dispatchable.length}\n`;
+                    output += `- 🚫 **Blocked:** ${blockedTasks.length}\n`;
+                    output += `- ⏱️ **Timed Out:** ${epicTimedOut.length}\n`;
+                    output += `- ❌ **Failed:** ${failedTasks.length}\n`;
+                    output += `- 📋 **Backlog:** ${epicStatus.byStatus.backlog || 0}\n\n`;
+                    // Dispatchable tasks
+                    if (dispatchable.length > 0) {
+                        output += `## Dispatchable Tasks (${dispatchable.length})\n\n`;
+                        for (const item of dispatchable) {
+                            output += `- **${item.task.title}** (\`${item.task.id}\`)\n`;
+                            output += `  - Worker: ${item.worker.name}\n`;
+                            output += `  - Effort: ${item.task.estimated_effort || 'unknown'}\n`;
+                        }
+                        output += `\n`;
+                    }
+                    // In-progress tasks
+                    if (activeCount.total > 0) {
+                        const inProgressResult = await listTasks(DEFAULT_USER_ID, projectId, {
+                            status: 'in_progress',
+                            parent_id: epicId,
+                            limit: 50,
+                        });
+                        if (inProgressResult.success && inProgressResult.data.length > 0) {
+                            output += `## In Progress (${inProgressResult.data.length})\n\n`;
+                            for (const task of inProgressResult.data) {
+                                output += `- **${task.title}** (\`${task.id}\`)\n`;
+                                output += `  - Assigned: ${task.assigned_to || 'None'}\n`;
+                                if (task.lock_expires_at) {
+                                    const expiresAt = new Date(task.lock_expires_at);
+                                    const now = new Date();
+                                    const isExpired = expiresAt < now;
+                                    output += `  - Lock: ${isExpired ? '⚠️ EXPIRED' : '✅ Active'}\n`;
+                                }
+                            }
+                            output += `\n`;
+                        }
+                    }
+                    // Timed-out tasks
+                    if (epicTimedOut.length > 0) {
+                        output += `## Timed Out (${epicTimedOut.length})\n\n`;
+                        for (const { task, timeSinceExpiry } of epicTimedOut) {
+                            const minutesAgo = Math.floor(timeSinceExpiry / 1000 / 60);
+                            output += `- **${task.title}** (\`${task.id}\`) - ${minutesAgo}m ago\n`;
+                        }
+                        output += `\n`;
+                    }
+                    // Blocked tasks
+                    if (blockedTasks.length > 0) {
+                        output += `## Blocked (${blockedTasks.length})\n\n`;
+                        for (const task of blockedTasks.slice(0, 5)) {
+                            const blockedBy = parseJsonArray(task.blocked_by);
+                            output += `- **${task.title}** (\`${task.id}\`)\n`;
+                            output += `  - Blocked by: ${blockedBy.join(', ')}\n`;
+                        }
+                        if (blockedTasks.length > 5) {
+                            output += `  ... and ${blockedTasks.length - 5} more\n`;
+                        }
+                        output += `\n`;
+                    }
+                    // Failed tasks
+                    if (failedTasks.length > 0) {
+                        output += `## Failed (${failedTasks.length})\n\n`;
+                        for (const task of failedTasks) {
+                            output += `- **${task.title}** (\`${task.id}\`)\n`;
+                        }
+                        output += `\n`;
+                    }
+                    // Next actions
+                    output += `---\n\n`;
+                    output += `## Next Actions\n\n`;
+                    const nextActions = [];
+                    if (status === 'complete') {
+                        nextActions.push('🎉 Epic complete! All tasks done.');
+                    }
+                    else if (status === 'failed') {
+                        nextActions.push(`❌ Epic stalled: ${failedTasks.length} failed task(s), no work remaining.`);
+                        nextActions.push('Review failed tasks or manually adjust epic status.');
+                    }
+                    else if (status === 'blocked') {
+                        nextActions.push(`🚫 Epic blocked: All remaining tasks are blocked or waiting.`);
+                        nextActions.push('Review dependencies or manually unblock tasks.');
+                    }
+                    else {
+                        // In progress - provide actionable next steps
+                        if (epicTimedOut.length > 0) {
+                            nextActions.push(`⏱️ Retry ${epicTimedOut.length} timed-out task(s) using task_auto_retry_timeouts`);
+                        }
+                        if (dispatchable.length > 0) {
+                            const canDispatch = Math.min(dispatchable.length, maxParallel - activeCount.total);
+                            if (canDispatch > 0) {
+                                nextActions.push(`🚀 Spawn ${canDispatch} worker(s) for dispatchable tasks using Task tool`);
+                                if (!dryRun) {
+                                    // Provide Task tool invocations
+                                    output += `\n**Spawn Commands:**\n\`\`\`\n`;
+                                    for (const item of dispatchable.slice(0, canDispatch)) {
+                                        const taskPrompt = `Execute task ${item.task.id}: ${item.task.title}. When complete, call task_complete(task_id="${item.task.id}", summary="...") with work summary.`;
+                                        output += `Task(subagent_type="general-purpose", prompt="${taskPrompt.replace(/"/g, '\\"')}")\n`;
+                                    }
+                                    output += `\`\`\`\n\n`;
+                                }
+                            }
+                            else {
+                                nextActions.push(`⏳ At capacity (${activeCount.total}/${maxParallel}). Wait for tasks to complete.`);
+                            }
+                        }
+                        if (dispatchable.length === 0 && activeCount.total > 0) {
+                            nextActions.push(`⏳ Monitor ${activeCount.total} in-progress task(s). No new work to dispatch.`);
+                        }
+                        if (dispatchable.length === 0 && activeCount.total === 0 && blockedTasks.length === 0 && failedTasks.length === 0) {
+                            nextActions.push('✅ Check epic status - may be complete or need refresh.');
+                        }
+                    }
+                    for (const action of nextActions) {
+                        output += `- ${action}\n`;
+                    }
+                    if (dryRun) {
+                        output += `\n**Note:** This is a dry run. No actions were taken.\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
                 // =========================================================================
                 // CODEBASE MAPPING HANDLERS
                 // =========================================================================
                 case 'codebase_map': {
-                    const result = await apiRequest(`/api/v1/codebase/${projectId}/map`);
-                    mcpLogger.toolResult(name, true, timer());
-                    if (!result.success || typeof result === 'object' && 'error' in result) {
+                    // Use raw fetch since this endpoint returns markdown, not JSON
+                    const url = `${API_BASE_URL}/api/v1/codebase/${projectId}/map`;
+                    const response = await fetch(url);
+                    mcpLogger.toolResult(name, response.ok, timer());
+                    if (!response.ok) {
                         return {
                             content: [{
                                     type: 'text',
@@ -942,8 +1390,9 @@ export function registerToolHandlers(server) {
                         };
                     }
                     // The API returns text/markdown directly
+                    const markdown = await response.text();
                     return {
-                        content: [{ type: 'text', text: result }],
+                        content: [{ type: 'text', text: markdown }],
                     };
                 }
                 case 'codebase_find': {
@@ -1085,6 +1534,136 @@ export function registerToolHandlers(server) {
                         content: [{ type: 'text', text: output }],
                     };
                 }
+                // =========================================================================
+                // DOCUMENTATION CACHING HANDLERS
+                // =========================================================================
+                case 'docs_cache': {
+                    const libraryName = args?.library_name || args?.library;
+                    const topic = args?.topic;
+                    const result = await cacheDocs(projectId, libraryName, libraryName, undefined, topic);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result.success) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# Failed to Cache Documentation\n\nCould not fetch documentation for "${libraryName}" from Context7.\n\nCheck if the library name is correct (e.g., "react", "next.js", "zod").`,
+                                }],
+                        };
+                    }
+                    let output = `# Documentation Cached\n\n`;
+                    output += `**Library:** ${libraryName}\n`;
+                    output += `**Status:** ${result.status || 'fetched'}\n`;
+                    if (result.size)
+                        output += `**Size:** ${result.size} bytes\n`;
+                    if (topic)
+                        output += `**Topic:** ${topic}\n`;
+                    output += `\nDocumentation is now cached from Context7 and available for task context injection.`;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'docs_list': {
+                    const result = await listCachedDocs(projectId);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (result.libraries.length === 0) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# No Cached Documentation\n\nNo documentation has been cached for this project yet.\n\nUse context7 to fetch docs, then \`docs_cache\` to store them.`,
+                                }],
+                        };
+                    }
+                    let output = `# Cached Documentation\n\n`;
+                    output += `**Libraries:** ${result.libraries.length}\n\n`;
+                    output += `| Library | ID | Topics | Cached |\n`;
+                    output += `|---------|----|---------|---------|\n`;
+                    for (const lib of result.libraries) {
+                        const topics = lib.topics?.join(', ') || 'general';
+                        const cached = new Date(lib.cached_at).toLocaleDateString();
+                        output += `| ${lib.library_name} | \`${lib.library_id}\` | ${topics} | ${cached} |\n`;
+                    }
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                case 'docs_get': {
+                    const library = args?.library;
+                    const topic = args?.topic;
+                    const result = await getCachedDocs(projectId, library, topic);
+                    mcpLogger.toolResult(name, true, timer());
+                    if (!result || !result.content) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `# Documentation Not Found\n\nNo cached documentation found for "${library}"${topic ? ` (topic: ${topic})` : ''}.\n\nUse \`docs_cache\` to fetch and cache the docs first.`,
+                                }],
+                        };
+                    }
+                    let output = `# Documentation: ${result.library_name || result.library || library}\n\n`;
+                    output += `**Context7 ID:** ${result.context7Id || 'N/A'}\n`;
+                    output += `**Fetched:** ${result.fetchedAt}\n`;
+                    output += `**Size:** ${result.size} bytes\n`;
+                    if (topic)
+                        output += `**Topic:** ${topic}\n`;
+                    output += `\n---\n\n`;
+                    output += result.content;
+                    return {
+                        content: [{ type: 'text', text: output }],
+                    };
+                }
+                // =========================================================================
+                // CODEDNA CODE GENERATION HANDLERS
+                // =========================================================================
+                case 'codedna_generate_api': {
+                    const result = await handleGenerateApi(args);
+                    mcpLogger.toolResult(name, true, timer());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
+                case 'codedna_generate_frontend': {
+                    const result = await handleGenerateFrontend(args);
+                    mcpLogger.toolResult(name, true, timer());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
+                case 'codedna_generate_component': {
+                    const result = await handleGenerateComponent(args);
+                    mcpLogger.toolResult(name, true, timer());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
+                case 'codedna_list_generators': {
+                    const result = await handleListGenerators();
+                    mcpLogger.toolResult(name, true, timer());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
+                case 'codedna_validate_spec': {
+                    const result = await handleValidateSpec(args);
+                    mcpLogger.toolResult(name, true, timer());
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            }],
+                    };
+                }
                 default:
                     throw new Error(`Unknown tool: ${name}`);
             }