code-graph-context 2.8.0 → 2.10.0

package/dist/mcp/mcp.server.js

@@ -16,6 +16,7 @@ const rootDir = join(__dirname, '..', '..');
 dotenv.config({ path: join(rootDir, '.env'), quiet: true });
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { stopEmbeddingSidecar } from '../core/embeddings/embedding-sidecar.js';
 import { MCP_SERVER_CONFIG, MESSAGES } from './constants.js';
 import { performIncrementalParse } from './handlers/incremental-parse.handler.js';
 import { initializeServices } from './service-init.js';
@@ -109,6 +110,7 @@ const shutdown = async (signal) => {
     await logServerStats(`shutdown-${signal}`);
     try {
         await watchManager.stopAllWatchers();
+        await stopEmbeddingSidecar();
         await debugLog('Shutdown complete', { signal });
     }
     catch (error) {

package/dist/mcp/service-init.js

@@ -5,6 +5,7 @@
 import fs from 'fs/promises';
 import { join } from 'path';
 import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning } from '../cli/neo4j-docker.js';
+import { isOpenAIEnabled, getEmbeddingDimensions } from '../core/embeddings/embeddings.service.js';
 import { Neo4jService, QUERIES } from '../storage/neo4j/neo4j.service.js';
 import { FILE_PATHS, LOG_CONFIG } from './constants.js';
 import { initializeNaturalLanguageService } from './tools/natural-language-to-cypher.tool.js';
@@ -13,12 +14,32 @@ import { debugLog } from './utils.js';
  * Log startup warnings for missing configuration
  */
 const checkConfiguration = async () => {
-    if (!process.env.OPENAI_API_KEY) {
+    const openai = isOpenAIEnabled();
+    const dims = getEmbeddingDimensions();
+    const provider = openai ? 'openai' : 'local';
+    console.error(JSON.stringify({
+        level: 'info',
+        message: `[code-graph-context] Embedding provider: ${provider} (${dims} dimensions)`,
+    }));
+    await debugLog('Embedding configuration', { provider, dimensions: dims });
+    if (openai && !process.env.OPENAI_API_KEY) {
         console.error(JSON.stringify({
             level: 'warn',
-            message: '[code-graph-context] OPENAI_API_KEY not set. Semantic search and NL queries unavailable.',
+            message: '[code-graph-context] OPENAI_ENABLED=true but OPENAI_API_KEY not set. Embedding calls will fail.',
         }));
-        await debugLog('Configuration warning', { warning: 'OPENAI_API_KEY not set' });
+        await debugLog('Configuration warning', { warning: 'OPENAI_ENABLED=true but OPENAI_API_KEY not set' });
+    }
+    if (!openai) {
+        console.error(JSON.stringify({
+            level: 'info',
+            message: '[code-graph-context] Using local embeddings (Python sidecar). Starts on first embedding request.',
+        }));
+        if (!process.env.OPENAI_API_KEY) {
+            console.error(JSON.stringify({
+                level: 'info',
+                message: '[code-graph-context] natural_language_to_cypher requires OPENAI_API_KEY and is unavailable.',
+            }));
+        }
     }
 };
 /**

package/dist/mcp/tools/index.js

@@ -21,6 +21,7 @@ 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 { createSwarmMessageTool } from './swarm-message.tool.js';
 import { createSwarmPheromoneTool } from './swarm-pheromone.tool.js';
 import { createSwarmPostTaskTool } from './swarm-post-task.tool.js';
 import { createSwarmSenseTool } from './swarm-sense.tool.js';
@@ -73,6 +74,8 @@ export const registerAllTools = (server) => {
     createSwarmClaimTaskTool(server);
     createSwarmCompleteTaskTool(server);
     createSwarmGetTasksTool(server);
+    // Register swarm messaging tools (direct agent-to-agent communication)
+    createSwarmMessageTool(server);
     // Register session bookmark tools (cross-session context continuity)
     createSaveSessionBookmarkTool(server);
     createRestoreSessionBookmarkTool(server);

package/dist/mcp/tools/search-codebase.tool.js

@@ -39,6 +39,12 @@ export const createSearchCodebaseTool = (server) => {
                 .optional()
                 .describe(`Length of code snippets to include (default: ${DEFAULTS.codeSnippetLength})`)
                 .default(DEFAULTS.codeSnippetLength),
+            topK: z
+                .number()
+                .int()
+                .optional()
+                .describe('Number of top vector matches to return (default: 3, max: 10). The best match is traversed; others shown as alternatives.')
+                .default(3),
             minSimilarity: z
                 .number()
                 .optional()
@@ -50,7 +56,7 @@ export const createSearchCodebaseTool = (server) => {
                 .describe('Use weighted traversal strategy that scores each node for relevance (default: false)')
                 .default(true),
         },
-    }, async ({ projectId, query, maxDepth = DEFAULTS.traversalDepth, maxNodesPerChain = 5, skip = 0, includeCode = true, snippetLength = DEFAULTS.codeSnippetLength, minSimilarity = 0.65, useWeightedTraversal = true, }) => {
+    }, async ({ projectId, query, maxDepth = DEFAULTS.traversalDepth, maxNodesPerChain = 5, skip = 0, includeCode = true, snippetLength = DEFAULTS.codeSnippetLength, topK = 3, minSimilarity = 0.65, useWeightedTraversal = true, }) => {
         const neo4jService = new Neo4jService();
         try {
             // Resolve project ID from name, path, or ID
@@ -63,11 +69,12 @@ export const createSearchCodebaseTool = (server) => {
             const sanitizedMaxNodesPerChain = sanitizeNumericInput(maxNodesPerChain, 5);
             const sanitizedSkip = sanitizeNumericInput(skip, 0);
             const sanitizedSnippetLength = sanitizeNumericInput(snippetLength, DEFAULTS.codeSnippetLength);
+            const sanitizedTopK = sanitizeNumericInput(topK, 3, 10);
             const embeddingsService = new EmbeddingsService();
             const traversalHandler = new TraversalHandler(neo4jService);
             const embedding = await embeddingsService.embedText(query);
             const vectorResults = await neo4jService.run(QUERIES.VECTOR_SEARCH, {
-                limit: 1,
+                limit: sanitizedTopK,
                 embedding,
                 projectId: resolvedProjectId,
                 fetchMultiplier: 10,
@@ -77,28 +84,45 @@ export const createSearchCodebaseTool = (server) => {
                 return createSuccessResponse(`No code found with similarity >= ${minSimilarity}. ` +
                     `Try rephrasing your query or lowering the minSimilarity threshold. Query: "${query}"`);
             }
-            const startNode = vectorResults[0].node;
-            const nodeId = startNode.properties.id;
-            const similarityScore = vectorResults[0].score;
-            // Check if best match meets threshold - prevents traversing low-relevance results
-            if (similarityScore < minSimilarity) {
-                return createSuccessResponse(`No sufficiently relevant code found. Best match score: ${similarityScore.toFixed(3)} ` +
+            // Filter results that meet the similarity threshold
+            const qualifiedResults = vectorResults.filter((r) => r.score >= minSimilarity);
+            if (qualifiedResults.length === 0) {
+                const bestScore = vectorResults[0].score;
+                return createSuccessResponse(`No sufficiently relevant code found. Best match score: ${bestScore.toFixed(3)} ` +
                     `(threshold: ${minSimilarity}). Try rephrasing your query.`);
             }
-            // Include similarity score in the title so users can see relevance
-            const scoreDisplay = typeof similarityScore === 'number' ? similarityScore.toFixed(3) : 'N/A';
-            return await traversalHandler.traverseFromNode(nodeId, embedding, {
+            // Best match — traverse from this node
+            const bestMatch = qualifiedResults[0];
+            const nodeId = bestMatch.node.properties.id;
+            const bestScore = bestMatch.score.toFixed(3);
+            // Build alternative matches summary for the response
+            const alternatives = qualifiedResults.slice(1);
+            const altLines = alternatives.map((r) => {
+                const props = r.node.properties;
+                const name = props.name ?? props.id;
+                const file = props.filePath ? ` (${props.filePath})` : '';
+                return `  - ${name}${file} [score: ${r.score.toFixed(3)}, id: ${props.id}]`;
+            });
+            const altSection = altLines.length > 0
+                ? `\n\nAlternative matches (use traverse_from_node to explore):\n${altLines.join('\n')}`
+                : '';
+            const traversalResult = await traversalHandler.traverseFromNode(nodeId, embedding, {
                 projectId: resolvedProjectId,
                 maxDepth: sanitizedMaxDepth,
-                direction: 'BOTH', // Show both incoming (who calls this) and outgoing (what this calls)
+                direction: 'BOTH',
                 includeCode,
                 maxNodesPerChain: sanitizedMaxNodesPerChain,
                 skip: sanitizedSkip,
                 summaryOnly: false,
                 snippetLength: sanitizedSnippetLength,
-                title: `Search Results (similarity: ${scoreDisplay}) - Starting from: ${nodeId}`,
+                title: `Search Results (${qualifiedResults.length} matches, best: ${bestScore}) - Traversing from: ${nodeId}`,
                 useWeightedTraversal,
             });
+            // Append alternatives to the traversal response
+            if (altSection && traversalResult.content?.[0]?.type === 'text') {
+                traversalResult.content[0].text += altSection;
+            }
+            return traversalResult;
         }
         catch (error) {
             console.error('Search codebase error:', error);

package/dist/mcp/tools/session-note.tool.js

@@ -3,7 +3,7 @@
  * Save and recall cross-session observations, decisions, and insights
  */
 import { z } from 'zod';
-import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
+import { EmbeddingsService, getEmbeddingDimensions } from '../../core/embeddings/embeddings.service.js';
 import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
 import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
@@ -31,17 +31,16 @@ const CREATE_SESSION_NOTE_QUERY = `
   // Link to referenced code nodes (filter out internal coordination nodes)
   WITH n
   UNWIND CASE WHEN size($aboutNodeIds) = 0 THEN [null] ELSE $aboutNodeIds END AS aboutNodeId
-  WITH n, aboutNodeId
-  WHERE aboutNodeId IS NOT NULL
   OPTIONAL MATCH (target)
-  WHERE target.id = aboutNodeId
+  WHERE aboutNodeId IS NOT NULL
+    AND target.id = aboutNodeId
     AND target.projectId = $projectId
     AND NOT target:SessionNote
     AND NOT target:SessionBookmark
     AND NOT target:Pheromone
     AND NOT target:SwarmTask
   WITH n, collect(target) AS targets
-  FOREACH (t IN targets | MERGE (n)-[:ABOUT]->(t))
+  FOREACH (t IN [x IN targets WHERE x IS NOT NULL] | MERGE (n)-[:ABOUT]->(t))
 
   // Link to the latest SessionBookmark for this session (if one exists)
   WITH n
@@ -194,7 +193,7 @@ export const createSaveSessionNoteTool = (server) => {
             // Ensure vector index exists (idempotent — IF NOT EXISTS)
             let hasEmbedding = false;
             try {
-                await neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX);
+                await neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX(getEmbeddingDimensions()));
                 const embeddingsService = new EmbeddingsService();
                 const embeddingText = `${topic}\n\n${content}`;
                 const embedding = await embeddingsService.embedText(embeddingText);

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

@@ -12,6 +12,7 @@ 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';
+import { PENDING_MESSAGES_FOR_AGENT_QUERY, AUTO_ACKNOWLEDGE_QUERY } from './swarm-message.tool.js';
 /** Maximum retries when racing for a task */
 const MAX_CLAIM_RETRIES = 3;
 /** Delay between retries (ms) */
@@ -435,6 +436,39 @@ export const createSwarmClaimTaskTool = (server) => {
                 name: t.name,
                 filePath: t.filePath,
             }));
+            // Fetch pending messages for this agent (direct delivery on claim)
+            let pendingMessages = [];
+            try {
+                const msgResult = await neo4jService.run(PENDING_MESSAGES_FOR_AGENT_QUERY, {
+                    projectId: resolvedProjectId,
+                    swarmId,
+                    agentId,
+                });
+                if (msgResult.length > 0) {
+                    pendingMessages = msgResult.map((m) => {
+                        const ts = typeof m.timestamp === 'object' && m.timestamp?.toNumber ? m.timestamp.toNumber() : m.timestamp;
+                        return {
+                            id: m.id,
+                            from: m.fromAgentId,
+                            category: m.category,
+                            content: m.content,
+                            taskId: m.taskId ?? undefined,
+                            filePaths: m.filePaths?.length > 0 ? m.filePaths : undefined,
+                            age: ts ? `${Math.round((Date.now() - ts) / 1000)}s ago` : null,
+                        };
+                    });
+                    // Auto-acknowledge delivered messages
+                    const deliveredIds = pendingMessages.map((m) => m.id);
+                    await neo4jService.run(AUTO_ACKNOWLEDGE_QUERY, {
+                        messageIds: deliveredIds,
+                        agentId,
+                    });
+                }
+            }
+            catch (msgError) {
+                // Non-fatal: message delivery failure shouldn't block task claim
+                await debugLog('Swarm claim task: message delivery failed (non-fatal)', { error: String(msgError) });
+            }
             // Slim response - only essential fields for agent to do work
             return createSuccessResponse(JSON.stringify({
                 action: actionLabel,
@@ -450,6 +484,7 @@ export const createSwarmClaimTaskTool = (server) => {
                     targetFilePaths: task.targetFilePaths,
                     ...(task.dependencies?.length > 0 && { dependencies: task.dependencies }),
                 },
+                ...(pendingMessages.length > 0 && { messages: pendingMessages }),
                 ...(retryCount > 0 && { retryAttempts: retryCount }),
             }));
         }

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

@@ -75,6 +75,22 @@ const COUNT_ALL_QUERY = `
   WHERE p.projectId = $projectId AND NOT p.type IN $keepTypes
   RETURN count(p) as count, collect(DISTINCT p.agentId) as agents, collect(DISTINCT p.swarmId) as swarms, collect(DISTINCT p.type) as types
 `;
+/**
+ * Neo4j query to delete SwarmMessage nodes by swarm ID
+ */
+const CLEANUP_MESSAGES_BY_SWARM_QUERY = `
+  MATCH (m:SwarmMessage)
+  WHERE m.projectId = $projectId
+    AND m.swarmId = $swarmId
+  WITH m, m.category as category
+  DELETE m
+  RETURN count(m) as deleted, collect(DISTINCT category) as categories
+`;
+const COUNT_MESSAGES_BY_SWARM_QUERY = `
+  MATCH (m:SwarmMessage)
+  WHERE m.projectId = $projectId AND m.swarmId = $swarmId
+  RETURN count(m) as count, collect(DISTINCT m.category) as categories
+`;
 export const createSwarmCleanupTool = (server) => {
     server.registerTool(TOOL_NAMES.swarmCleanup, {
         title: TOOL_METADATA[TOOL_NAMES.swarmCleanup].title,
@@ -143,6 +159,15 @@ export const createSwarmCleanupTool = (server) => {
                         typeof taskCount === 'object' && 'toNumber' in taskCount ? taskCount.toNumber() : taskCount;
                     taskStatuses = taskResult[0]?.statuses ?? [];
                 }
+                let messageCount = 0;
+                let messageCategories = [];
+                if (swarmId) {
+                    const msgResult = await neo4jService.run(COUNT_MESSAGES_BY_SWARM_QUERY, params);
+                    messageCount = msgResult[0]?.count ?? 0;
+                    messageCount =
+                        typeof messageCount === 'object' && 'toNumber' in messageCount ? messageCount.toNumber() : messageCount;
+                    messageCategories = msgResult[0]?.categories ?? [];
+                }
                 return createSuccessResponse(JSON.stringify({
                     success: true,
                     dryRun: true,
@@ -160,6 +185,12 @@ export const createSwarmCleanupTool = (server) => {
                             statuses: taskStatuses,
                         }
                         : null,
+                    messages: swarmId
+                        ? {
+                            wouldDelete: messageCount,
+                            categories: messageCategories,
+                        }
+                        : null,
                     keepTypes,
                     projectId: resolvedProjectId,
                 }));
@@ -179,6 +210,23 @@ export const createSwarmCleanupTool = (server) => {
                         : tasksDeleted;
                 taskStatuses = taskResult[0]?.statuses ?? [];
             }
+            // Delete messages if swarmId provided
+            let messagesDeleted = 0;
+            let messageCategories = [];
+            if (swarmId) {
+                const msgResult = await neo4jService.run(CLEANUP_MESSAGES_BY_SWARM_QUERY, params);
+                messagesDeleted = msgResult[0]?.deleted ?? 0;
+                messagesDeleted =
+                    typeof messagesDeleted === 'object' && 'toNumber' in messagesDeleted
+                        ? messagesDeleted.toNumber()
+                        : messagesDeleted;
+                messageCategories = msgResult[0]?.categories ?? [];
+            }
+            const parts = [`${pheromonesDeleted} pheromones`];
+            if (swarmId && includeTasks)
+                parts.push(`${tasksDeleted} tasks`);
+            if (swarmId)
+                parts.push(`${messagesDeleted} messages`);
             return createSuccessResponse(JSON.stringify({
                 success: true,
                 mode,
@@ -195,11 +243,15 @@ export const createSwarmCleanupTool = (server) => {
                         statuses: taskStatuses,
                     }
                     : null,
+                messages: swarmId
+                    ? {
+                        deleted: messagesDeleted,
+                        categories: messageCategories,
+                    }
+                    : null,
                 keepTypes,
                 projectId: resolvedProjectId,
-                message: swarmId && includeTasks
-                    ? `Cleaned up ${pheromonesDeleted} pheromones and ${tasksDeleted} tasks`
-                    : `Cleaned up ${pheromonesDeleted} pheromones`,
+                message: `Cleaned up ${parts.join(', ')}`,
             }));
         }
         catch (error) {

package/dist/mcp/tools/swarm-constants.js

@@ -79,6 +79,34 @@ export const WORKFLOW_STATES = ['exploring', 'claiming', 'modifying', 'completed
  */
 export const FLAG_TYPES = ['warning', 'proposal', 'needs_review', 'session_context'];
 // ============================================================================
+// SWARM MESSAGING CONSTANTS
+// ============================================================================
+/**
+ * Message categories for direct agent-to-agent communication.
+ * Unlike pheromones (passive, decay-based), messages are explicit and persistent until read.
+ */
+export const MESSAGE_CATEGORIES = {
+    blocked: 'Agent is blocked and needs help',
+    conflict: 'File or resource conflict detected',
+    finding: 'Important discovery another agent should know',
+    request: 'Direct request to another agent',
+    alert: 'Urgent notification (e.g., breaking change, test failure)',
+    handoff: 'Context handoff between agents (e.g., partial work)',
+};
+export const MESSAGE_CATEGORY_KEYS = Object.keys(MESSAGE_CATEGORIES);
+/**
+ * Default TTL for messages (4 hours). Messages older than this are auto-cleaned.
+ */
+export const MESSAGE_DEFAULT_TTL_MS = 4 * 60 * 60 * 1000;
+/**
+ * Generate a unique message ID
+ */
+export const generateMessageId = () => {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `msg_${timestamp}_${random}`;
+};
+// ============================================================================
 // ORCHESTRATOR CONSTANTS
 // ============================================================================
 /**