code-graph-context 2.7.0 → 2.9.0

package/README.md

@@ -345,7 +345,6 @@ Explicit task management with dependencies:
 
 | Tool | Purpose |
 |------|---------|
-| `swarm_orchestrate` | Decompose a task and spawn worker agents |
 | `swarm_post_task` | Add a task to the queue |
 | `swarm_get_tasks` | Query tasks with filters |
 | `swarm_claim_task` | Claim/start/release a task |
@@ -357,28 +356,20 @@ Explicit task management with dependencies:
 ### Example: Parallel Refactoring
 
 ```typescript
-// Orchestrator decomposes and creates tasks
-swarm_orchestrate({
+// Orchestrator decomposes the task and creates individual work items
+swarm_post_task({
   projectId: "backend",
-  task: "Rename getUserById to findUserById across the codebase",
-  maxAgents: 3
+  swarmId: "swarm_rename_user",
+  title: "Update UserService.findUserById",
+  description: "Rename getUserById to findUserById in UserService",
+  type: "refactor",
+  createdBy: "orchestrator"
 })
 
-// Returns a plan:
-{
-  swarmId: "swarm_abc123",
-  plan: {
-    totalTasks: 12,
-    parallelizable: 8,
-    sequential: 4,  // These have dependencies
-    tasks: [
-      { id: "task_1", title: "Update UserService.findUserById", status: "available" },
-      { id: "task_2", title: "Update UserController references", status: "blocked", depends: ["task_1"] },
-      ...
-    ]
-  },
-  workerInstructions: "..."  // Copy-paste to spawn workers
-}
+// Workers claim and execute tasks
+swarm_claim_task({ projectId: "backend", swarmId: "swarm_rename_user", agentId: "worker_1" })
+// ... do work ...
+swarm_complete_task({ taskId: "task_1", agentId: "worker_1", action: "complete", summary: "Renamed method" })
 ```
 
 ### Install the Swarm Skill
@@ -428,7 +419,6 @@ See [`skills/swarm/SKILL.md`](skills/swarm/SKILL.md) for the full documentation.
 | `stop_watch_project` | Stop file watching |
 | `list_watchers` | List active file watchers |
 | **Swarm** | |
-| `swarm_orchestrate` | Plan and spawn parallel agents |
 | `swarm_post_task` | Add task to the queue |
 | `swarm_get_tasks` | Query tasks |
 | `swarm_claim_task` | Claim/start/release tasks |
@@ -458,7 +448,7 @@ detect_dead_code → detect_duplicate_code → prioritize cleanup
 
 **Pattern 4: Multi-Agent Work**
 ```
-swarm_orchestrate → spawn workers → swarm_get_tasks(includeStats) → swarm_cleanup
+swarm_post_task → swarm_claim_task → swarm_complete_task → swarm_get_tasks(includeStats) → swarm_cleanup
 ```
 
 ### Multi-Project Support

package/dist/mcp/constants.js

@@ -38,11 +38,12 @@ export const TOOL_NAMES = {
     swarmClaimTask: 'swarm_claim_task',
     swarmCompleteTask: 'swarm_complete_task',
     swarmGetTasks: 'swarm_get_tasks',
-    swarmOrchestrate: 'swarm_orchestrate',
     saveSessionBookmark: 'save_session_bookmark',
     restoreSessionBookmark: 'restore_session_bookmark',
     saveSessionNote: 'save_session_note',
     recallSessionNotes: 'recall_session_notes',
+    cleanupSession: 'cleanup_session',
+    swarmMessage: 'swarm_message',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -221,7 +222,7 @@ Returns pheromones with current intensity after decay. minIntensity default: 0.3
     },
     [TOOL_NAMES.swarmCleanup]: {
         title: 'Swarm Cleanup',
-        description: `Bulk delete pheromones. Specify swarmId, agentId, or all:true. Warning pheromones preserved by default (override with keepTypes:[]). Use dryRun:true to preview.`,
+        description: `Bulk delete pheromones, tasks, and messages. Specify swarmId, agentId, or all:true. Warning pheromones preserved by default (override with keepTypes:[]). Messages and tasks are deleted when swarmId is provided. Use dryRun:true to preview.`,
     },
     [TOOL_NAMES.swarmPostTask]: {
         title: 'Swarm Post Task',
@@ -258,12 +259,6 @@ Complete unblocks dependent tasks. Failed tasks can be retried if retryable=true
         description: `Query tasks with filters. Use taskId for single task, or filter by swarmId, statuses, types, claimedBy, createdBy, minPriority.
 
 Sort by: priority (default), created, updated. Add includeStats:true for aggregate counts.`,
-    },
-    [TOOL_NAMES.swarmOrchestrate]: {
-        title: 'Swarm Orchestrate',
-        description: `Coordinate multiple agents for complex multi-file tasks. Analyzes codebase, decomposes into atomic tasks, spawns workers, monitors progress.
-
-Use dryRun:true to preview plan. maxAgents controls parallelism (default: 3). Failed tasks auto-retry via pheromone decay.`,
     },
     [TOOL_NAMES.saveSessionBookmark]: {
         title: 'Save Session Bookmark',
@@ -334,6 +329,43 @@ Parameters:
 
 Returns notes with topic, content, category, severity, relevance score (vector mode), and linked aboutNodes.`,
     },
+    [TOOL_NAMES.cleanupSession]: {
+        title: 'Cleanup Session',
+        description: `Clean up expired session notes and old session bookmarks.
+
+Removes:
+- Expired SessionNote nodes (past expiresAt) and their edges
+- Old SessionBookmark nodes, keeping only the most recent N per session (default: 3)
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- keepBookmarks (default: 3): Number of most recent bookmarks to keep per session
+- dryRun (default: false): Preview what would be deleted without deleting
+
+Returns counts of deleted notes, bookmarks, and edges.`,
+    },
+    [TOOL_NAMES.swarmMessage]: {
+        title: 'Swarm Message',
+        description: `Direct agent-to-agent messaging via Neo4j. Unlike pheromones (passive/decay-based), messages are explicit and delivered when agents claim tasks.
+
+**Actions:**
+- send: Post a message to a specific agent or broadcast to all agents in a swarm
+- read: Retrieve unread messages (or all messages) for an agent
+- acknowledge: Mark messages as read
+
+**Categories:** blocked, conflict, finding, request, alert, handoff
+
+**Key behavior:**
+- Messages sent to a specific agent are delivered when that agent calls swarm_claim_task
+- Broadcast messages (toAgentId omitted) are visible to all agents in the swarm
+- Messages auto-expire after 4 hours (configurable via ttlMs)
+- Use this for critical coordination signals that agents MUST see, not optional context
+
+**Examples:**
+- Agent finds a breaking type error: send alert to all
+- Agent is blocked on a file another agent owns: send blocked to that agent
+- Agent discovers context another agent needs: send finding to that agent`,
+    },
 };
 // Default Values
 export const DEFAULTS = {

package/dist/mcp/handlers/graph-generator.handler.js

@@ -74,6 +74,9 @@ export class GraphGeneratorHandler {
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_EMBEDDED);
         await this.neo4jService.run(QUERIES.CREATE_PROJECT_ID_INDEX_SOURCEFILE);
         await this.neo4jService.run(QUERIES.CREATE_NORMALIZED_HASH_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_BOOKMARK_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTE_CATEGORY_INDEX);
         await debugLog('Project indexes created');
     }
     async importNodes(nodes, batchSize) {

package/dist/mcp/tools/index.js

@@ -13,6 +13,7 @@ import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
 import { createRestoreSessionBookmarkTool, createSaveSessionBookmarkTool } from './session-bookmark.tool.js';
+import { createCleanupSessionTool } from './session-cleanup.tool.js';
 import { createRecallSessionNotesTool, createSaveSessionNoteTool } from './session-note.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
@@ -20,7 +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 { createSwarmOrchestrateTool } from './swarm-orchestrate.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,12 +74,14 @@ export const registerAllTools = (server) => {
     createSwarmClaimTaskTool(server);
     createSwarmCompleteTaskTool(server);
     createSwarmGetTasksTool(server);
-    // Register swarm orchestration tool (meta-tool for coordinating multi-agent work)
-    createSwarmOrchestrateTool(server);
+    // Register swarm messaging tools (direct agent-to-agent communication)
+    createSwarmMessageTool(server);
     // Register session bookmark tools (cross-session context continuity)
     createSaveSessionBookmarkTool(server);
     createRestoreSessionBookmarkTool(server);
     // Register session note tools (durable observations and decisions)
     createSaveSessionNoteTool(server);
     createRecallSessionNotesTool(server);
+    // Register session cleanup tool
+    createCleanupSessionTool(server);
 };

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

@@ -96,11 +96,24 @@ const GET_SESSION_NOTES_QUERY = `
   MATCH (n:SessionNote)
   WHERE n.projectId = $projectId
     AND n.sessionId = $sessionId
+    AND (n.expiresAt IS NULL OR n.expiresAt > timestamp())
+
+  OPTIONAL MATCH (n)-[:ABOUT]->(codeNode)
+  WHERE NOT codeNode:SessionNote
+    AND NOT codeNode:SessionBookmark
+    AND NOT codeNode:Pheromone
+    AND NOT codeNode:SwarmTask
+
   RETURN n.id AS id,
-         n.sessionId AS sessionId,
-         n.agentId AS agentId,
+         n.topic AS topic,
          n.content AS content,
-         n.createdAt AS createdAt
+         n.category AS category,
+         n.severity AS severity,
+         n.agentId AS agentId,
+         n.sessionId AS sessionId,
+         n.createdAt AS createdAt,
+         n.expiresAt AS expiresAt,
+         collect(DISTINCT {id: codeNode.id, name: codeNode.name, filePath: codeNode.filePath}) AS aboutNodes
   ORDER BY n.createdAt ASC
   LIMIT 50
 `;
@@ -266,13 +279,21 @@ export const createRestoreSessionBookmarkTool = (server) => {
                 }
                 return node;
             });
-            const notes = noteRows.map((n) => ({
-                id: n.id,
-                sessionId: n.sessionId,
-                agentId: n.agentId,
-                content: n.content,
-                createdAt: typeof n.createdAt === 'object' && n.createdAt?.toNumber ? n.createdAt.toNumber() : n.createdAt,
-            }));
+            const notes = noteRows.map((n) => {
+                const aboutNodes = (n.aboutNodes ?? []).filter((node) => node?.id != null);
+                return {
+                    id: n.id,
+                    topic: n.topic,
+                    content: n.content,
+                    category: n.category,
+                    severity: n.severity,
+                    agentId: n.agentId,
+                    sessionId: n.sessionId,
+                    createdAt: typeof n.createdAt === 'object' && n.createdAt?.toNumber ? n.createdAt.toNumber() : n.createdAt,
+                    expiresAt: typeof n.expiresAt === 'object' && n.expiresAt?.toNumber ? n.expiresAt.toNumber() : n.expiresAt,
+                    aboutNodes,
+                };
+            });
             // Identify working set nodes not found in the graph (stale IDs after re-parse)
             const foundIds = new Set(workingSetRows.map((r) => r.id));
             const storedIds = Array.isArray(bm.workingSetNodeIds) ? bm.workingSetNodeIds : [];

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

@@ -0,0 +1,139 @@
+/**
+ * Session Cleanup Tool
+ * Remove expired notes and prune old bookmarks
+ */
+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';
+/**
+ * Count expired notes (for dry run)
+ */
+const COUNT_EXPIRED_NOTES_QUERY = `
+  MATCH (n:SessionNote)
+  WHERE n.projectId = $projectId
+    AND n.expiresAt IS NOT NULL
+    AND n.expiresAt <= timestamp()
+  RETURN count(n) AS count
+`;
+/**
+ * Delete expired notes and their edges
+ */
+const DELETE_EXPIRED_NOTES_QUERY = `
+  MATCH (n:SessionNote)
+  WHERE n.projectId = $projectId
+    AND n.expiresAt IS NOT NULL
+    AND n.expiresAt <= timestamp()
+  WITH collect(n) AS toDelete
+  WITH size(toDelete) AS cnt, toDelete
+  FOREACH (n IN toDelete | DETACH DELETE n)
+  RETURN cnt AS deleted
+`;
+/**
+ * Find old bookmarks to prune (keeping N most recent per session)
+ */
+const COUNT_OLD_BOOKMARKS_QUERY = `
+  MATCH (b:SessionBookmark)
+  WHERE b.projectId = $projectId
+  WITH b.sessionId AS sessionId, b
+  ORDER BY b.createdAt DESC
+  WITH sessionId, collect(b) AS bookmarks
+  WHERE size(bookmarks) > $keepBookmarks
+  UNWIND bookmarks[$keepBookmarks..] AS old
+  RETURN count(old) AS count
+`;
+/**
+ * Delete old bookmarks (keeping N most recent per session)
+ */
+const DELETE_OLD_BOOKMARKS_QUERY = `
+  MATCH (b:SessionBookmark)
+  WHERE b.projectId = $projectId
+  WITH b.sessionId AS sessionId, b
+  ORDER BY b.createdAt DESC
+  WITH sessionId, collect(b) AS bookmarks
+  WHERE size(bookmarks) > $keepBookmarks
+  WITH reduce(all = [], bs IN collect(bookmarks[$keepBookmarks..]) | all + bs) AS toDelete
+  WITH size(toDelete) AS cnt, toDelete
+  FOREACH (b IN toDelete | DETACH DELETE b)
+  RETURN cnt AS deleted
+`;
+export const createCleanupSessionTool = (server) => {
+    server.registerTool(TOOL_NAMES.cleanupSession, {
+        title: TOOL_METADATA[TOOL_NAMES.cleanupSession].title,
+        description: TOOL_METADATA[TOOL_NAMES.cleanupSession].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            keepBookmarks: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(3)
+                .describe('Number of most recent bookmarks to keep per session (default: 3)'),
+            dryRun: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Preview what would be deleted without deleting (default: false)'),
+        },
+    }, async ({ projectId, keepBookmarks = 3, dryRun = false }) => {
+        const neo4jService = new Neo4jService();
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            const params = { projectId: resolvedProjectId, keepBookmarks };
+            if (dryRun) {
+                const [noteCount, bookmarkCount] = await Promise.all([
+                    neo4jService.run(COUNT_EXPIRED_NOTES_QUERY, params),
+                    neo4jService.run(COUNT_OLD_BOOKMARKS_QUERY, params),
+                ]);
+                const expiredNotes = noteCount[0]?.count ?? 0;
+                const oldBookmarks = bookmarkCount[0]?.count ?? 0;
+                const toNumber = (v) => (typeof v === 'object' && v?.toNumber ? v.toNumber() : v);
+                return createSuccessResponse(JSON.stringify({
+                    dryRun: true,
+                    projectId: resolvedProjectId,
+                    wouldDelete: {
+                        expiredNotes: toNumber(expiredNotes),
+                        oldBookmarks: toNumber(oldBookmarks),
+                    },
+                    keepBookmarks,
+                    message: toNumber(expiredNotes) === 0 && toNumber(oldBookmarks) === 0
+                        ? 'Nothing to clean up.'
+                        : `Would delete ${toNumber(expiredNotes)} expired notes and ${toNumber(oldBookmarks)} old bookmarks.`,
+                }));
+            }
+            const [noteResult, bookmarkResult] = await Promise.all([
+                neo4jService.run(DELETE_EXPIRED_NOTES_QUERY, params),
+                neo4jService.run(DELETE_OLD_BOOKMARKS_QUERY, params),
+            ]);
+            const toNumber = (v) => (typeof v === 'object' && v?.toNumber ? v.toNumber() : v);
+            const deletedNotes = toNumber(noteResult[0]?.deleted ?? 0);
+            const deletedBookmarks = toNumber(bookmarkResult[0]?.deleted ?? 0);
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                projectId: resolvedProjectId,
+                deleted: {
+                    expiredNotes: deletedNotes,
+                    oldBookmarks: deletedBookmarks,
+                },
+                keepBookmarks,
+                message: deletedNotes === 0 && deletedBookmarks === 0
+                    ? 'Nothing to clean up.'
+                    : `Deleted ${deletedNotes} expired notes and ${deletedBookmarks} old bookmarks.`,
+            }));
+        }
+        catch (error) {
+            await debugLog('Cleanup session error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};

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
 // ============================================================================
 /**