code-graph-context 2.4.5 → 2.5.0

package/dist/mcp/tools/swarm-orchestrate.tool.js

@@ -0,0 +1,389 @@
+/**
+ * Swarm Orchestrate Tool
+ * Orchestrates multiple agents to tackle complex, multi-file code tasks in parallel
+ *
+ * This is the main entry point for swarm-based task execution. It:
+ * 1. Analyzes the task using semantic search and impact analysis
+ * 2. Decomposes the task into atomic, dependency-ordered SwarmTasks
+ * 3. Creates tasks on the blackboard for worker agents
+ * 4. Returns execution plan for agents to claim and execute
+ */
+import { z } from 'zod';
+import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { TaskDecompositionHandler, } from '../handlers/task-decomposition.handler.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+import { TASK_PRIORITIES, generateSwarmId, ORCHESTRATOR_CONFIG, } from './swarm-constants.js';
+/**
+ * Query to search for nodes matching the task description
+ */
+const SEMANTIC_SEARCH_QUERY = `
+  CALL db.index.vector.queryNodes('code_embeddings', toInteger($limit), $embedding)
+  YIELD node, score
+  WHERE node.projectId = $projectId
+    AND score >= $minSimilarity
+  RETURN node.id AS id,
+         node.name AS name,
+         node.coreType AS coreType,
+         node.semanticType AS semanticType,
+         node.filePath AS filePath,
+         substring(node.sourceCode, 0, 500) AS sourceCode,
+         node.startLine AS startLine,
+         node.endLine AS endLine,
+         score
+  ORDER BY score DESC
+  LIMIT toInteger($limit)
+`;
+/**
+ * Query to get impact analysis for a node
+ */
+const IMPACT_QUERY = `
+  MATCH (target)
+  WHERE target.id = $nodeId AND target.projectId = $projectId
+  OPTIONAL MATCH (dependent)-[r]->(target)
+  WHERE dependent.projectId = $projectId
+    AND NOT dependent:Pheromone
+    AND NOT dependent:SwarmTask
+  WITH target, collect(DISTINCT {
+    nodeId: dependent.id,
+    filePath: dependent.filePath,
+    relType: type(r)
+  }) AS dependents
+  RETURN target.id AS nodeId,
+         size(dependents) AS dependentCount,
+         [d IN dependents | d.filePath] AS affectedFiles,
+         CASE
+           WHEN size(dependents) >= 20 THEN 'CRITICAL'
+           WHEN size(dependents) >= 10 THEN 'HIGH'
+           WHEN size(dependents) >= 5 THEN 'MEDIUM'
+           ELSE 'LOW'
+         END AS riskLevel
+`;
+/**
+ * Query to create a pheromone marker on a node
+ */
+const CREATE_PHEROMONE_QUERY = `
+  MATCH (target)
+  WHERE target.id = $nodeId AND target.projectId = $projectId
+  MERGE (p:Pheromone {
+    nodeId: $nodeId,
+    agentId: $agentId,
+    type: $type,
+    projectId: $projectId
+  })
+  ON CREATE SET
+    p.swarmId = $swarmId,
+    p.intensity = $intensity,
+    p.createdAt = timestamp(),
+    p.updatedAt = timestamp(),
+    p.data = $data
+  ON MATCH SET
+    p.intensity = $intensity,
+    p.updatedAt = timestamp(),
+    p.data = $data
+  MERGE (p)-[:MARKS]->(target)
+  RETURN p.nodeId AS nodeId
+`;
+/**
+ * Query to create a SwarmTask node
+ */
+const CREATE_TASK_QUERY = `
+  CREATE (t:SwarmTask {
+    id: $taskId,
+    projectId: $projectId,
+    swarmId: $swarmId,
+    title: $title,
+    description: $description,
+    type: $type,
+    priority: $priority,
+    priorityScore: $priorityScore,
+    status: $status,
+    targetNodeIds: $targetNodeIds,
+    targetFilePaths: $targetFilePaths,
+    dependencies: $dependencies,
+    createdBy: $createdBy,
+    createdAt: timestamp(),
+    updatedAt: timestamp(),
+    metadata: $metadata
+  })
+  RETURN t.id AS id
+`;
+export const createSwarmOrchestrateTool = (server) => {
+    const embeddingsService = new EmbeddingsService();
+    const taskDecomposer = new TaskDecompositionHandler();
+    server.registerTool(TOOL_NAMES.swarmOrchestrate, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmOrchestrate].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmOrchestrate].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path'),
+            task: z.string().min(10).describe('Natural language description of the task to execute'),
+            maxAgents: z
+                .number()
+                .int()
+                .min(1)
+                .max(ORCHESTRATOR_CONFIG.maxAgentsLimit)
+                .optional()
+                .default(ORCHESTRATOR_CONFIG.defaultMaxAgents)
+                .describe(`Maximum concurrent worker agents (default: ${ORCHESTRATOR_CONFIG.defaultMaxAgents})`),
+            dryRun: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, only plan without creating tasks (default: false)'),
+            priority: z
+                .enum(Object.keys(TASK_PRIORITIES))
+                .optional()
+                .default('normal')
+                .describe('Overall priority level for tasks'),
+            minSimilarity: z
+                .number()
+                .min(0.5)
+                .max(1.0)
+                .optional()
+                .default(0.65)
+                .describe('Minimum similarity score for semantic search (default: 0.65)'),
+            maxNodes: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(50)
+                .describe('Maximum nodes to consider from search (default: 50)'),
+        },
+    }, async ({ projectId, task, maxAgents = ORCHESTRATOR_CONFIG.defaultMaxAgents, dryRun = false, priority = 'normal', minSimilarity = 0.65, maxNodes = 50, }) => {
+        const neo4jService = new Neo4jService();
+        const swarmId = generateSwarmId();
+        try {
+            // Step 1: Resolve project ID
+            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            if (!projectResult.success) {
+                await neo4jService.close();
+                return projectResult.error;
+            }
+            const resolvedProjectId = projectResult.projectId;
+            await debugLog('Swarm orchestration started', {
+                swarmId,
+                projectId: resolvedProjectId,
+                task,
+                maxAgents,
+                dryRun,
+            });
+            // Step 2: Semantic search to find affected nodes
+            await debugLog('Searching for affected nodes', { task });
+            let embedding;
+            try {
+                embedding = await embeddingsService.embedText(task);
+            }
+            catch (error) {
+                return createErrorResponse(`Failed to generate embedding for task description: ${error}`);
+            }
+            const searchResults = await neo4jService.run(SEMANTIC_SEARCH_QUERY, {
+                projectId: resolvedProjectId,
+                embedding,
+                minSimilarity,
+                limit: Math.floor(maxNodes),
+            });
+            if (searchResults.length === 0) {
+                return createErrorResponse(`No code found matching task: "${task}". Try rephrasing or use search_codebase to explore the codebase first.`);
+            }
+            const affectedNodes = searchResults.map((r) => ({
+                id: r.id,
+                name: r.name,
+                coreType: r.coreType,
+                semanticType: r.semanticType,
+                filePath: r.filePath,
+                sourceCode: r.sourceCode,
+                startLine: typeof r.startLine === 'object' ? r.startLine.toNumber() : r.startLine,
+                endLine: typeof r.endLine === 'object' ? r.endLine.toNumber() : r.endLine,
+            }));
+            await debugLog('Found affected nodes', {
+                count: affectedNodes.length,
+                files: [...new Set(affectedNodes.map((n) => n.filePath))].length,
+            });
+            // Step 3: Run impact analysis on each node
+            await debugLog('Running impact analysis', { nodeCount: affectedNodes.length });
+            const impactMap = new Map();
+            for (const node of affectedNodes) {
+                const impactResult = await neo4jService.run(IMPACT_QUERY, {
+                    nodeId: node.id,
+                    projectId: resolvedProjectId,
+                });
+                if (impactResult.length > 0) {
+                    const impact = impactResult[0];
+                    impactMap.set(node.id, {
+                        nodeId: node.id,
+                        riskLevel: impact.riskLevel,
+                        directDependents: {
+                            count: typeof impact.dependentCount === 'object'
+                                ? impact.dependentCount.toNumber()
+                                : impact.dependentCount,
+                            byType: {},
+                        },
+                        transitiveDependents: { count: 0 },
+                        affectedFiles: impact.affectedFiles ?? [],
+                    });
+                }
+            }
+            // Step 4: Decompose task into atomic tasks
+            await debugLog('Decomposing task', { nodeCount: affectedNodes.length });
+            const decomposition = await taskDecomposer.decomposeTask(task, affectedNodes, impactMap, priority);
+            if (decomposition.tasks.length === 0) {
+                return createErrorResponse('Task decomposition produced no actionable tasks');
+            }
+            await debugLog('Task decomposition complete', {
+                totalTasks: decomposition.tasks.length,
+                parallelizable: decomposition.summary.parallelizable,
+            });
+            // Step 5: Create SwarmTasks on the blackboard (unless dry run)
+            if (!dryRun) {
+                await debugLog('Creating SwarmTasks', { count: decomposition.tasks.length });
+                for (const atomicTask of decomposition.tasks) {
+                    // Determine initial status based on dependencies
+                    const hasUnmetDeps = atomicTask.dependencies.length > 0;
+                    const initialStatus = hasUnmetDeps ? 'blocked' : 'available';
+                    await neo4jService.run(CREATE_TASK_QUERY, {
+                        taskId: atomicTask.id,
+                        projectId: resolvedProjectId,
+                        swarmId,
+                        title: atomicTask.title,
+                        description: atomicTask.description,
+                        type: atomicTask.type,
+                        priority: atomicTask.priority,
+                        priorityScore: atomicTask.priorityScore,
+                        status: initialStatus,
+                        targetNodeIds: atomicTask.nodeIds,
+                        targetFilePaths: [atomicTask.filePath],
+                        dependencies: atomicTask.dependencies,
+                        createdBy: 'orchestrator',
+                        metadata: JSON.stringify(atomicTask.metadata ?? {}),
+                    });
+                }
+                await debugLog('SwarmTasks created', { swarmId, count: decomposition.tasks.length });
+                // Step 5b: Leave "proposal" pheromones on all target nodes
+                // This signals to other agents that work is planned for these nodes
+                const uniqueNodeIds = new Set();
+                for (const atomicTask of decomposition.tasks) {
+                    for (const nodeId of atomicTask.nodeIds) {
+                        uniqueNodeIds.add(nodeId);
+                    }
+                }
+                await debugLog('Creating proposal pheromones', { nodeCount: uniqueNodeIds.size });
+                for (const nodeId of uniqueNodeIds) {
+                    await neo4jService.run(CREATE_PHEROMONE_QUERY, {
+                        nodeId,
+                        projectId: resolvedProjectId,
+                        agentId: 'orchestrator',
+                        swarmId,
+                        type: 'proposal',
+                        intensity: 1.0,
+                        data: JSON.stringify({ task, swarmId }),
+                    });
+                }
+                await debugLog('Proposal pheromones created', { swarmId, count: uniqueNodeIds.size });
+            }
+            // Step 6: Generate worker instructions
+            const workerInstructions = generateWorkerInstructions(swarmId, resolvedProjectId, maxAgents, decomposition.tasks.length);
+            // Step 7: Build result
+            const result = {
+                swarmId,
+                status: dryRun ? 'planning' : 'ready',
+                plan: {
+                    totalTasks: decomposition.tasks.length,
+                    parallelizable: decomposition.summary.parallelizable,
+                    sequential: decomposition.summary.sequential,
+                    estimatedComplexity: decomposition.summary.estimatedComplexity,
+                    tasks: decomposition.tasks.map((t) => ({
+                        id: t.id,
+                        title: t.title,
+                        type: t.type,
+                        priority: t.priority,
+                        status: t.dependencies.length > 0 ? 'blocked' : 'available',
+                        dependencyCount: t.dependencies.length,
+                        targetFiles: [t.filePath],
+                    })),
+                    dependencyGraph: buildDependencyGraph(decomposition),
+                },
+                workerInstructions,
+                message: dryRun
+                    ? `Dry run complete. ${decomposition.tasks.length} tasks planned but not created.`
+                    : `Swarm ready! ${decomposition.tasks.length} tasks created. ${decomposition.summary.parallelizable} can run in parallel.`,
+            };
+            await debugLog('Swarm orchestration complete', {
+                swarmId,
+                status: result.status,
+                totalTasks: result.plan.totalTasks,
+            });
+            return createSuccessResponse(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            await debugLog('Swarm orchestration error', { swarmId, error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};
+/**
+ * Generate instructions for spawning worker agents
+ */
+function generateWorkerInstructions(swarmId, projectId, maxAgents, taskCount) {
+    const recommendedAgents = Math.min(maxAgents, Math.ceil(taskCount / 2), taskCount);
+    return `
+## Worker Agent Instructions
+
+To execute this swarm, spawn ${recommendedAgents} worker agent(s) using the Task tool:
+
+\`\`\`
+Task({
+  subagent_type: "general-purpose",
+  prompt: "You are a swarm worker for swarm ${swarmId}. Project: ${projectId}.
+
+Your workflow:
+1. swarm_sense({ projectId: '${projectId}', swarmId: '${swarmId}', types: ['modifying', 'claiming'] })
+2. swarm_claim_task({ projectId: '${projectId}', swarmId: '${swarmId}', agentId: '<your-id>' })
+3. If task claimed: execute it, then swarm_complete_task with action: 'complete'
+4. Loop until no tasks remain
+
+Always leave pheromones when working. Exit when swarm_get_tasks shows no available/in_progress tasks.",
+  run_in_background: true
+})
+\`\`\`
+
+Launch ${recommendedAgents} agents in parallel for optimal execution.
+
+## Monitoring Progress
+
+Check swarm progress:
+\`\`\`
+swarm_get_tasks({
+  projectId: "${projectId}",
+  swarmId: "${swarmId}",
+  includeStats: true
+})
+\`\`\`
+
+## Cleanup (after completion)
+
+\`\`\`
+swarm_cleanup({
+  projectId: "${projectId}",
+  swarmId: "${swarmId}"
+})
+\`\`\`
+`;
+}
+/**
+ * Build dependency graph edges for visualization
+ */
+function buildDependencyGraph(decomposition) {
+    const edges = [];
+    for (const task of decomposition.tasks) {
+        for (const depId of task.dependencies) {
+            edges.push({ from: depId, to: task.id });
+        }
+    }
+    return edges;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * Swarm Post Task Tool
+ * Post a task to the blackboard for agents to claim and work on
+ */
+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_PRIORITIES, TASK_TYPES, generateTaskId, } from './swarm-constants.js';
+/**
+ * Neo4j query to create a new SwarmTask node
+ */
+const CREATE_TASK_QUERY = `
+  // Create the task node
+  CREATE (t:SwarmTask {
+    id: $taskId,
+    projectId: $projectId,
+    swarmId: $swarmId,
+    title: $title,
+    description: $description,
+    type: $type,
+    priority: $priority,
+    priorityScore: $priorityScore,
+    status: 'available',
+    targetNodeIds: $targetNodeIds,
+    targetFilePaths: $targetFilePaths,
+    dependencies: $dependencies,
+    createdBy: $createdBy,
+    createdAt: timestamp(),
+    updatedAt: timestamp(),
+    metadata: $metadata
+  })
+
+  // Link to target code nodes if they exist
+  WITH t
+  OPTIONAL MATCH (target)
+  WHERE target.id IN $targetNodeIds
+    AND target.projectId = $projectId
+    AND NOT target:SwarmTask
+    AND NOT target:Pheromone
+  WITH t, collect(DISTINCT target) as targets
+  FOREACH (target IN targets | MERGE (t)-[:TARGETS]->(target))
+
+  // Link to dependency tasks if they exist
+  WITH t
+  OPTIONAL MATCH (dep:SwarmTask)
+  WHERE dep.id IN $dependencies
+    AND dep.projectId = $projectId
+  WITH t, collect(DISTINCT dep) as deps
+  FOREACH (dep IN deps | MERGE (t)-[:DEPENDS_ON]->(dep))
+
+  // Return the created task
+  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.createdBy as createdBy,
+         t.createdAt as createdAt
+`;
+/**
+ * Query to check if dependencies are met (all completed or no dependencies)
+ */
+const CHECK_DEPENDENCIES_QUERY = `
+  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
+  OPTIONAL MATCH (t)-[:DEPENDS_ON]->(dep:SwarmTask)
+  WITH t, collect(dep) as deps,
+       [d IN collect(dep) WHERE d.status <> 'completed'] as incompleteDeps
+  RETURN size(deps) as totalDeps,
+         size(incompleteDeps) as incompleteDeps,
+         [d IN incompleteDeps | {id: d.id, title: d.title, status: d.status}] as blockedBy
+`;
+export const createSwarmPostTaskTool = (server) => {
+    server.registerTool(TOOL_NAMES.swarmPostTask, {
+        title: TOOL_METADATA[TOOL_NAMES.swarmPostTask].title,
+        description: TOOL_METADATA[TOOL_NAMES.swarmPostTask].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path'),
+            swarmId: z.string().describe('Swarm ID for grouping related tasks'),
+            title: z.string().min(1).max(200).describe('Short title for the task'),
+            description: z.string().describe('Detailed description of what needs to be done'),
+            type: z
+                .enum(TASK_TYPES)
+                .optional()
+                .default('implement')
+                .describe('Task type: implement, refactor, fix, test, review, document, investigate, plan'),
+            priority: z
+                .enum(Object.keys(TASK_PRIORITIES))
+                .optional()
+                .default('normal')
+                .describe('Priority level: critical, high, normal, low, backlog'),
+            targetNodeIds: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe('Code node IDs this task targets (from search_codebase)'),
+            targetFilePaths: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe('File paths this task affects (alternative to nodeIds)'),
+            dependencies: z
+                .array(z.string())
+                .optional()
+                .default([])
+                .describe('Task IDs that must be completed before this task can start'),
+            createdBy: z.string().describe('Agent ID or identifier of who created this task'),
+            metadata: z
+                .record(z.unknown())
+                .optional()
+                .describe('Additional metadata (context, acceptance criteria, etc.)'),
+        },
+    }, async ({ projectId, swarmId, title, description, type = 'implement', priority = 'normal', targetNodeIds = [], targetFilePaths = [], dependencies = [], createdBy, metadata, }) => {
+        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 {
+            const taskId = generateTaskId();
+            const priorityScore = TASK_PRIORITIES[priority];
+            const metadataJson = metadata ? JSON.stringify(metadata) : null;
+            await debugLog('Creating swarm task', {
+                taskId,
+                projectId: resolvedProjectId,
+                swarmId,
+                title,
+                type,
+                priority,
+                targetNodeIds: targetNodeIds.length,
+                dependencies: dependencies.length,
+            });
+            // Create the task
+            const result = await neo4jService.run(CREATE_TASK_QUERY, {
+                taskId,
+                projectId: resolvedProjectId,
+                swarmId,
+                title,
+                description,
+                type,
+                priority,
+                priorityScore,
+                targetNodeIds,
+                targetFilePaths,
+                dependencies,
+                createdBy,
+                metadata: metadataJson,
+            });
+            if (result.length === 0) {
+                return createErrorResponse('Failed to create task');
+            }
+            const task = result[0];
+            // Check dependency status
+            let dependencyStatus = { totalDeps: 0, incompleteDeps: 0, blockedBy: [] };
+            if (dependencies.length > 0) {
+                const depCheck = await neo4jService.run(CHECK_DEPENDENCIES_QUERY, {
+                    taskId,
+                    projectId: resolvedProjectId,
+                });
+                if (depCheck.length > 0) {
+                    dependencyStatus = {
+                        totalDeps: typeof depCheck[0].totalDeps === 'object'
+                            ? depCheck[0].totalDeps.toNumber()
+                            : depCheck[0].totalDeps,
+                        incompleteDeps: typeof depCheck[0].incompleteDeps === 'object'
+                            ? depCheck[0].incompleteDeps.toNumber()
+                            : depCheck[0].incompleteDeps,
+                        blockedBy: depCheck[0].blockedBy || [],
+                    };
+                }
+            }
+            const isBlocked = dependencyStatus.incompleteDeps > 0;
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                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: isBlocked ? 'blocked' : 'available',
+                    targetNodeIds: task.targetNodeIds,
+                    targetFilePaths: task.targetFilePaths,
+                    dependencies: task.dependencies,
+                    createdBy: task.createdBy,
+                    createdAt: typeof task.createdAt === 'object'
+                        ? task.createdAt.toNumber()
+                        : task.createdAt,
+                },
+                dependencyStatus: {
+                    isBlocked,
+                    ...dependencyStatus,
+                },
+                message: isBlocked
+                    ? `Task created but blocked by ${dependencyStatus.incompleteDeps} incomplete dependencies`
+                    : 'Task created and available for claiming',
+            }));
+        }
+        catch (error) {
+            await debugLog('Swarm post task error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-context",
-  "version": "2.4.5",
+  "version": "2.5.0",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
   "homepage": "https://github.com/drewdrewH/code-graph-context#readme",