code-graph-context 2.4.5 → 2.5.1

package/dist/mcp/handlers/task-decomposition.handler.js

@@ -0,0 +1,294 @@
+/**
+ * Task Decomposition Handler
+ * Transforms high-level natural language tasks into atomic, dependency-ordered SwarmTasks
+ */
+import path from 'path';
+import { TASK_PRIORITIES, TASK_INFERENCE_PATTERNS, generateTaskId, } from '../tools/swarm-constants.js';
+import { debugLog } from '../utils.js';
+/**
+ * TaskDecompositionHandler - Breaks down complex tasks into atomic units
+ */
+export class TaskDecompositionHandler {
+    /**
+     * Decompose a high-level task into atomic, dependency-ordered tasks
+     */
+    async decomposeTask(taskDescription, affectedNodes, impactMap, basePriority = 'normal') {
+        await debugLog('Decomposing task', {
+            task: taskDescription,
+            nodeCount: affectedNodes.length,
+        });
+        // Step 1: Infer task type from description
+        const taskType = this.inferTaskType(taskDescription);
+        // Step 2: Group nodes by file
+        const fileGroups = this.groupNodesByFile(affectedNodes);
+        // Step 3: Create atomic tasks for each file
+        const tasks = [];
+        const taskIdsByFile = new Map();
+        for (const [filePath, nodes] of fileGroups.entries()) {
+            const taskId = generateTaskId();
+            taskIdsByFile.set(filePath, taskId);
+            // Get the highest impact level for nodes in this file
+            const impactLevel = this.getHighestImpactLevel(nodes, impactMap);
+            // Adjust priority based on impact
+            const adjustedPriority = this.adjustPriorityByImpact(basePriority, impactLevel);
+            const task = {
+                id: taskId,
+                title: this.generateTaskTitle(taskDescription, filePath, nodes),
+                description: this.generateTaskDescription(taskDescription, nodes),
+                type: taskType,
+                priority: adjustedPriority,
+                priorityScore: TASK_PRIORITIES[adjustedPriority],
+                impactLevel,
+                nodeIds: nodes.map((n) => n.id),
+                filePath,
+                dependencies: [], // Will be filled in next step
+                affectedNodes: nodes,
+                metadata: {
+                    nodeCount: nodes.length,
+                    nodeTypes: this.getNodeTypeSummary(nodes),
+                },
+            };
+            tasks.push(task);
+        }
+        // Step 4: Calculate dependencies based on impact analysis
+        const dependencyGraph = this.calculateDependencies(tasks, impactMap);
+        // Step 5: Update task dependencies
+        for (const task of tasks) {
+            task.dependencies = dependencyGraph.get(task.id) ?? [];
+        }
+        // Step 6: Topological sort for execution order
+        const executionOrder = this.topologicalSort(tasks, dependencyGraph);
+        // Step 7: Calculate parallelization potential
+        const parallelizable = tasks.filter((t) => t.dependencies.length === 0).length;
+        const sequential = tasks.length - parallelizable;
+        const result = {
+            tasks,
+            dependencyGraph,
+            executionOrder,
+            summary: {
+                totalTasks: tasks.length,
+                parallelizable,
+                sequential,
+                estimatedComplexity: this.estimateComplexity(tasks, impactMap),
+            },
+        };
+        await debugLog('Task decomposition complete', {
+            totalTasks: tasks.length,
+            parallelizable,
+            sequential,
+        });
+        return result;
+    }
+    /**
+     * Infer task type from natural language description
+     */
+    inferTaskType(description) {
+        const lowerDesc = description.toLowerCase();
+        for (const [, pattern] of Object.entries(TASK_INFERENCE_PATTERNS)) {
+            for (const keyword of pattern.keywords) {
+                if (lowerDesc.includes(keyword)) {
+                    return pattern.taskType;
+                }
+            }
+        }
+        // Default to 'implement' if no pattern matches
+        return 'implement';
+    }
+    /**
+     * Group nodes by their file path
+     */
+    groupNodesByFile(nodes) {
+        const groups = new Map();
+        for (const node of nodes) {
+            const filePath = node.filePath;
+            if (!groups.has(filePath)) {
+                groups.set(filePath, []);
+            }
+            groups.get(filePath).push(node);
+        }
+        return groups;
+    }
+    /**
+     * Get the highest impact level among a set of nodes
+     */
+    getHighestImpactLevel(nodes, impactMap) {
+        const levels = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+        let highestIndex = 0;
+        for (const node of nodes) {
+            const impact = impactMap.get(node.id);
+            if (impact) {
+                const index = levels.indexOf(impact.riskLevel);
+                if (index > highestIndex) {
+                    highestIndex = index;
+                }
+            }
+        }
+        return levels[highestIndex];
+    }
+    /**
+     * Adjust priority based on impact level
+     */
+    adjustPriorityByImpact(basePriority, impactLevel) {
+        const priorityOrder = ['backlog', 'low', 'normal', 'high', 'critical'];
+        const currentIndex = priorityOrder.indexOf(basePriority);
+        // Bump priority for high-impact tasks (they need more attention)
+        if (impactLevel === 'CRITICAL' && currentIndex < 4) {
+            return priorityOrder[Math.min(currentIndex + 2, 4)];
+        }
+        if (impactLevel === 'HIGH' && currentIndex < 3) {
+            return priorityOrder[Math.min(currentIndex + 1, 3)];
+        }
+        return basePriority;
+    }
+    /**
+     * Generate a concise task title
+     */
+    generateTaskTitle(taskDescription, filePath, nodes) {
+        const fileName = path.basename(filePath);
+        const primaryNode = nodes[0];
+        const nodeType = primaryNode?.semanticType ?? primaryNode?.coreType ?? 'code';
+        // Extract action word from task description
+        const actionMatch = taskDescription.match(/^(\w+)/i);
+        const action = actionMatch ? actionMatch[1] : 'Update';
+        if (nodes.length === 1) {
+            return `${action} ${primaryNode.name} in ${fileName}`;
+        }
+        return `${action} ${nodes.length} ${nodeType}s in ${fileName}`;
+    }
+    /**
+     * Generate detailed task description
+     */
+    generateTaskDescription(taskDescription, nodes) {
+        const nodeList = nodes
+            .slice(0, 5)
+            .map((n) => `- ${n.name} (${n.semanticType ?? n.coreType})`)
+            .join('\n');
+        const moreText = nodes.length > 5 ? `\n... and ${nodes.length - 5} more` : '';
+        return `${taskDescription}
+
+Affected code elements:
+${nodeList}${moreText}`;
+    }
+    /**
+     * Get summary of node types
+     */
+    getNodeTypeSummary(nodes) {
+        const summary = {};
+        for (const node of nodes) {
+            const type = node.semanticType ?? node.coreType;
+            summary[type] = (summary[type] ?? 0) + 1;
+        }
+        return summary;
+    }
+    /**
+     * Calculate dependencies between tasks based on impact analysis
+     *
+     * Logic: If file A depends on file B (B is in A's affected files),
+     * then the task for A should wait for B's task to complete.
+     * This ensures changes propagate correctly through the dependency chain.
+     */
+    calculateDependencies(tasks, impactMap) {
+        const taskByFile = new Map();
+        for (const task of tasks) {
+            taskByFile.set(task.filePath, task);
+        }
+        const dependencies = new Map();
+        for (const task of tasks) {
+            const deps = [];
+            // Check each node in this task for dependencies
+            for (const nodeId of task.nodeIds) {
+                const impact = impactMap.get(nodeId);
+                if (!impact)
+                    continue;
+                // If this node depends on files that have their own tasks,
+                // those tasks should complete first
+                for (const affectedFile of impact.affectedFiles) {
+                    const depTask = taskByFile.get(affectedFile);
+                    if (depTask && depTask.id !== task.id && !deps.includes(depTask.id)) {
+                        deps.push(depTask.id);
+                    }
+                }
+            }
+            dependencies.set(task.id, deps);
+        }
+        return dependencies;
+    }
+    /**
+     * Topological sort to determine execution order
+     * Returns task IDs in order: tasks with no dependencies first
+     */
+    topologicalSort(tasks, dependencyGraph) {
+        const result = [];
+        const visited = new Set();
+        const visiting = new Set();
+        const taskMap = new Map();
+        for (const task of tasks) {
+            taskMap.set(task.id, task);
+        }
+        const visit = (taskId) => {
+            if (visited.has(taskId))
+                return;
+            if (visiting.has(taskId)) {
+                // Cycle detected - skip to avoid infinite loop
+                // In practice, this means the tasks can run in either order
+                return;
+            }
+            visiting.add(taskId);
+            const deps = dependencyGraph.get(taskId) ?? [];
+            for (const depId of deps) {
+                visit(depId);
+            }
+            visiting.delete(taskId);
+            visited.add(taskId);
+            result.push(taskId);
+        };
+        // Visit all tasks, prioritizing those with fewer dependencies
+        const sortedTasks = [...tasks].sort((a, b) => (dependencyGraph.get(a.id)?.length ?? 0) - (dependencyGraph.get(b.id)?.length ?? 0));
+        for (const task of sortedTasks) {
+            visit(task.id);
+        }
+        return result;
+    }
+    /**
+     * Estimate overall complexity of the decomposed tasks
+     */
+    estimateComplexity(tasks, impactMap) {
+        // Consider: number of tasks, dependency depth, impact levels
+        const taskCount = tasks.length;
+        const criticalCount = tasks.filter((t) => t.impactLevel === 'CRITICAL').length;
+        const highCount = tasks.filter((t) => t.impactLevel === 'HIGH').length;
+        // Calculate max dependency chain depth
+        let maxDepth = 0;
+        for (const task of tasks) {
+            maxDepth = Math.max(maxDepth, task.dependencies.length);
+        }
+        // Scoring
+        let score = 0;
+        score += Math.min(taskCount / 10, 3); // Up to 3 points for task count
+        score += criticalCount * 1.5; // 1.5 points per critical task
+        score += highCount * 0.5; // 0.5 points per high-impact task
+        score += maxDepth * 0.3; // 0.3 points per dependency depth level
+        if (score >= 5)
+            return 'HIGH';
+        if (score >= 2)
+            return 'MEDIUM';
+        return 'LOW';
+    }
+    /**
+     * Get tasks that can run in parallel (no pending dependencies)
+     */
+    getParallelizableTasks(allTasks, completedTaskIds) {
+        return allTasks.filter((task) => {
+            // Already completed
+            if (completedTaskIds.has(task.id))
+                return false;
+            // Check if all dependencies are completed
+            const deps = task.dependencies;
+            return deps.every((depId) => completedTaskIds.has(depId));
+        });
+    }
+}
+/**
+ * Export singleton instance
+ */
+export const taskDecompositionHandler = new TaskDecompositionHandler();

package/dist/mcp/tools/index.js

@@ -15,8 +15,13 @@ import { createParseTypescriptProjectTool } from './parse-typescript-project.too
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
+import { createSwarmClaimTaskTool } from './swarm-claim-task.tool.js';
 import { createSwarmCleanupTool } from './swarm-cleanup.tool.js';
+import { createSwarmCompleteTaskTool } from './swarm-complete-task.tool.js';
+import { createSwarmGetTasksTool } from './swarm-get-tasks.tool.js';
+import { createSwarmOrchestrateTool } from './swarm-orchestrate.tool.js';
 import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
+import { createSwarmPostTaskTool } from './swarm-post-task.tool.js';
 import { createSwarmSenseTool } from './swarm-sense.tool.js';
 import { createTestNeo4jConnectionTool } from './test-neo4j-connection.tool.js';
 import { createTraverseFromNodeTool } from './traverse-from-node.tool.js';
@@ -68,8 +73,15 @@ export const registerAllTools = (server) => {
     createStartWatchProjectTool(server);
     createStopWatchProjectTool(server);
     createListWatchersTool(server);
-    // Register swarm coordination tools
+    // Register swarm coordination tools (pheromones for indirect coordination)
     createSwarmPheromoneTool(server);
     createSwarmSenseTool(server);
     createSwarmCleanupTool(server);
+    // Register swarm task tools (blackboard for explicit task management)
+    createSwarmPostTaskTool(server);
+    createSwarmClaimTaskTool(server);
+    createSwarmCompleteTaskTool(server);
+    createSwarmGetTasksTool(server);
+    // Register swarm orchestration tool (meta-tool for coordinating multi-agent work)
+    createSwarmOrchestrateTool(server);
 };

package/dist/mcp/tools/swarm-claim-task.tool.js

@@ -0,0 +1,331 @@
+/**
+ * Swarm Claim Task Tool
+ * Allow an agent to claim an available task from the blackboard
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { TASK_TYPES, TASK_PRIORITIES } from './swarm-constants.js';
+/**
+ * Query to claim a specific task by ID
+ * Uses atomic update to prevent race conditions
+ */
+const CLAIM_TASK_BY_ID_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status IN ['available', 'blocked']
+
+  // Check if dependencies are complete
+  OPTIONAL MATCH (t)-[:DEPENDS_ON]->(dep:SwarmTask)
+  WHERE dep.status <> 'completed'
+  WITH t, count(dep) as incompleteDeps
+
+  // Only claim if all dependencies are complete
+  WHERE incompleteDeps = 0
+
+  // Atomic claim
+  SET t.status = 'claimed',
+      t.claimedBy = $agentId,
+      t.claimedAt = timestamp(),
+      t.updatedAt = timestamp()
+
+  // Return task details with target info
+  WITH t
+  OPTIONAL MATCH (t)-[:TARGETS]->(target)
+  RETURN t.id as id,
+         t.projectId as projectId,
+         t.swarmId as swarmId,
+         t.title as title,
+         t.description as description,
+         t.type as type,
+         t.priority as priority,
+         t.priorityScore as priorityScore,
+         t.status as status,
+         t.targetNodeIds as targetNodeIds,
+         t.targetFilePaths as targetFilePaths,
+         t.dependencies as dependencies,
+         t.claimedBy as claimedBy,
+         t.claimedAt as claimedAt,
+         t.createdBy as createdBy,
+         t.metadata as metadata,
+         collect(DISTINCT {
+           id: target.id,
+           type: labels(target)[0],
+           name: target.name,
+           filePath: target.filePath
+         }) as targets
+`;
+/**
+ * Query to claim the highest priority available task matching criteria
+ */
+const CLAIM_NEXT_TASK_QUERY = `
+  // Find available tasks not blocked by dependencies
+  MATCH (t:SwarmTask {projectId: $projectId, swarmId: $swarmId})
+  WHERE t.status = 'available'
+    AND ($types IS NULL OR size($types) = 0 OR t.type IN $types)
+    AND ($minPriority IS NULL OR t.priorityScore >= $minPriority)
+
+  // Exclude tasks with incomplete dependencies
+  OPTIONAL MATCH (t)-[:DEPENDS_ON]->(dep:SwarmTask)
+  WHERE dep.status <> 'completed'
+  WITH t, count(dep) as incompleteDeps
+  WHERE incompleteDeps = 0
+
+  // Order by priority (highest first), then by creation time (oldest first)
+  ORDER BY t.priorityScore DESC, t.createdAt ASC
+  LIMIT 1
+
+  // Atomic claim
+  SET t.status = 'claimed',
+      t.claimedBy = $agentId,
+      t.claimedAt = timestamp(),
+      t.updatedAt = timestamp()
+
+  // Return task details with target info
+  WITH t
+  OPTIONAL MATCH (t)-[:TARGETS]->(target)
+  RETURN t.id as id,
+         t.projectId as projectId,
+         t.swarmId as swarmId,
+         t.title as title,
+         t.description as description,
+         t.type as type,
+         t.priority as priority,
+         t.priorityScore as priorityScore,
+         t.status as status,
+         t.targetNodeIds as targetNodeIds,
+         t.targetFilePaths as targetFilePaths,
+         t.dependencies as dependencies,
+         t.claimedBy as claimedBy,
+         t.claimedAt as claimedAt,
+         t.createdBy as createdBy,
+         t.metadata as metadata,
+         collect(DISTINCT {
+           id: target.id,
+           type: labels(target)[0],
+           name: target.name,
+           filePath: target.filePath
+         }) as targets
+`;
+/**
+ * Query to start working on a claimed task (transition to in_progress)
+ */
+const START_TASK_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status = 'claimed' AND t.claimedBy = $agentId
+
+  SET t.status = 'in_progress',
+      t.startedAt = timestamp(),
+      t.updatedAt = timestamp()
+
+  RETURN t.id as id,
+         t.status as status,
+         t.claimedBy as claimedBy,
+         t.startedAt as startedAt
+`;
+/**
+ * Query to release a claimed task (unclaim it)
+ */
+const RELEASE_TASK_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  WHERE t.status IN ['claimed', 'in_progress'] AND t.claimedBy = $agentId
+
+  SET t.status = 'available',
+      t.claimedBy = null,
+      t.claimedAt = null,
+      t.startedAt = null,
+      t.updatedAt = timestamp(),
+      t.releaseReason = $reason
+
+  RETURN t.id as id,
+         t.title as title,
+         t.status as status
+`;
+export const createSwarmClaimTaskTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmClaimTask, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmClaimTask].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmClaimTask].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path'),
+            swarmId: z.string().describe('Swarm ID to find tasks in'),
+            agentId: z.string().describe('Your unique agent identifier'),
+            taskId: z
+                .string()
+                .optional()
+                .describe('Specific task ID to claim (if omitted, claims highest priority available task)'),
+            types: z
+                .array(z.enum(TASK_TYPES))
+                .optional()
+                .describe('Filter by task types when auto-selecting (e.g., ["implement", "fix"])'),
+            minPriority: z
+                .enum(Object.keys(TASK_PRIORITIES))
+                .optional()
+                .describe('Minimum priority level when auto-selecting'),
+            action: z
+                .enum(['claim', 'start', 'release'])
+                .optional()
+                .default('claim')
+                .describe('Action: claim (reserve task), start (begin work), release (give up task)'),
+            releaseReason: z
+                .string()
+                .optional()
+                .describe('Reason for releasing the task (required if action=release)'),
+        },
+    }, async ({ projectId, swarmId, agentId, taskId, types, minPriority, action = 'claim', releaseReason, }) => {
+        const neo4jService = new Neo4jService();
+        // Resolve project ID
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            await debugLog('Swarm claim task', {
+                action,
+                projectId: resolvedProjectId,
+                swarmId,
+                agentId,
+                taskId,
+                types,
+                minPriority,
+            });
+            // Handle release action
+            if (action === 'release') {
+                if (!taskId) {
+                    return createErrorResponse('taskId is required for release action');
+                }
+                const result = await neo4jService.run(RELEASE_TASK_QUERY, {
+                    taskId,
+                    projectId: resolvedProjectId,
+                    agentId,
+                    reason: releaseReason || 'No reason provided',
+                });
+                if (result.length === 0) {
+                    return createErrorResponse(`Cannot release task ${taskId}. Either it doesn't exist, isn't claimed/in_progress, or you don't own it.`);
+                }
+                return createSuccessResponse(JSON.stringify({
+                    success: true,
+                    action: 'released',
+                    task: {
+                        id: result[0].id,
+                        title: result[0].title,
+                        status: result[0].status,
+                    },
+                    message: `Task released and now available for other agents`,
+                }));
+            }
+            // Handle start action
+            if (action === 'start') {
+                if (!taskId) {
+                    return createErrorResponse('taskId is required for start action');
+                }
+                const result = await neo4jService.run(START_TASK_QUERY, {
+                    taskId,
+                    projectId: resolvedProjectId,
+                    agentId,
+                });
+                if (result.length === 0) {
+                    return createErrorResponse(`Cannot start task ${taskId}. Either it doesn't exist, isn't claimed, or you don't own it.`);
+                }
+                return createSuccessResponse(JSON.stringify({
+                    success: true,
+                    action: 'started',
+                    task: {
+                        id: result[0].id,
+                        status: result[0].status,
+                        claimedBy: result[0].claimedBy,
+                        startedAt: typeof result[0].startedAt === 'object'
+                            ? result[0].startedAt.toNumber()
+                            : result[0].startedAt,
+                    },
+                    message: 'Task is now in progress',
+                }));
+            }
+            // Handle claim action
+            let result;
+            if (taskId) {
+                // Claim specific task
+                result = await neo4jService.run(CLAIM_TASK_BY_ID_QUERY, {
+                    taskId,
+                    projectId: resolvedProjectId,
+                    agentId,
+                });
+                if (result.length === 0) {
+                    return createErrorResponse(`Cannot claim task ${taskId}. It may not exist, already be claimed, or have incomplete dependencies.`);
+                }
+            }
+            else {
+                // Auto-select highest priority available task
+                const minPriorityScore = minPriority
+                    ? TASK_PRIORITIES[minPriority]
+                    : null;
+                result = await neo4jService.run(CLAIM_NEXT_TASK_QUERY, {
+                    projectId: resolvedProjectId,
+                    swarmId,
+                    agentId,
+                    types: types || null,
+                    minPriority: minPriorityScore,
+                });
+                if (result.length === 0) {
+                    return createSuccessResponse(JSON.stringify({
+                        success: true,
+                        action: 'no_tasks',
+                        message: 'No available tasks matching criteria. All tasks may be claimed, blocked, or completed.',
+                        filters: {
+                            swarmId,
+                            types: types || 'any',
+                            minPriority: minPriority || 'any',
+                        },
+                    }));
+                }
+            }
+            const task = result[0];
+            // Parse metadata if present
+            let metadata = null;
+            if (task.metadata) {
+                try {
+                    metadata = JSON.parse(task.metadata);
+                }
+                catch {
+                    metadata = task.metadata;
+                }
+            }
+            // Filter out null targets
+            const targets = (task.targets || []).filter((t) => t.id !== null);
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                action: 'claimed',
+                task: {
+                    id: task.id,
+                    projectId: task.projectId,
+                    swarmId: task.swarmId,
+                    title: task.title,
+                    description: task.description,
+                    type: task.type,
+                    priority: task.priority,
+                    priorityScore: task.priorityScore,
+                    status: task.status,
+                    targetNodeIds: task.targetNodeIds,
+                    targetFilePaths: task.targetFilePaths,
+                    dependencies: task.dependencies,
+                    claimedBy: task.claimedBy,
+                    claimedAt: typeof task.claimedAt === 'object'
+                        ? task.claimedAt.toNumber()
+                        : task.claimedAt,
+                    createdBy: task.createdBy,
+                    metadata,
+                    targets,
+                },
+                message: 'Task claimed successfully. Use action="start" when you begin working.',
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm claim task error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};