code-graph-context 2.14.1 → 3.0.0

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

@@ -2,239 +2,16 @@
  * Swarm Claim Task Tool
  * Allow an agent to claim an available task from the blackboard
  *
- * Phase 1 improvements:
- * - Atomic claim_and_start action (eliminates race window)
- * - Retry logic on race loss
- * - Recovery actions (abandon, force_start)
+ * Handles claim and claim_and_start only.
+ * Release, abandon, force_start, and start actions are handled by dedicated tools.
  */
 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 { SwarmClaimHandler } from '../handlers/swarm/index.js';
+import { createEmptyResponse, 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) */
-const RETRY_DELAY_BASE_MS = 50;
-/**
- * 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
-
-  // Acquire exclusive lock to prevent race conditions
-  CALL apoc.lock.nodes([t])
-
-  // Double-check status after acquiring lock
-  WITH t WHERE t.status IN ['available', 'blocked']
-
-  // Atomic claim
-  SET t.status = $targetStatus,
-      t.claimedBy = $agentId,
-      t.claimedAt = timestamp(),
-      t.startedAt = CASE WHEN $targetStatus = 'in_progress' THEN timestamp() ELSE null END,
-      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.startedAt as startedAt,
-         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
- * Uses APOC locking to prevent race conditions between parallel workers
- * Supports both 'claimed' and 'in_progress' target states for atomic claim_and_start
- */
-const CLAIM_NEXT_TASK_QUERY = `
-  // Find available or blocked tasks (blocked tasks may have deps completed now)
-  MATCH (t:SwarmTask {projectId: $projectId, swarmId: $swarmId})
-  WHERE t.status IN ['available', 'blocked']
-    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
-
-  // Re-establish context for ordering (required by Cypher syntax)
-  WITH t
-  ORDER BY t.priorityScore DESC, t.createdAt ASC
-  LIMIT 1
-
-  // Acquire exclusive lock to prevent race conditions
-  CALL apoc.lock.nodes([t])
-
-  // Double-check status after acquiring lock (another worker may have claimed it)
-  WITH t WHERE t.status IN ['available', 'blocked']
-
-  // Atomic claim - supports both claim and claim_and_start via $targetStatus
-  SET t.status = $targetStatus,
-      t.claimedBy = $agentId,
-      t.claimedAt = timestamp(),
-      t.startedAt = CASE WHEN $targetStatus = 'in_progress' THEN timestamp() ELSE null END,
-      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.startedAt as startedAt,
-         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
-`;
-/**
- * Query to abandon a task - releases it with tracking for debugging
- * More explicit than release, tracks abandon history
- */
-const ABANDON_TASK_QUERY = `
-  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
-  WHERE t.claimedBy = $agentId
-    AND t.status IN ['claimed', 'in_progress']
-
-  // Track abandon history
-  SET t.status = 'available',
-      t.previousClaimedBy = t.claimedBy,
-      t.claimedBy = null,
-      t.claimedAt = null,
-      t.startedAt = null,
-      t.updatedAt = timestamp(),
-      t.abandonedBy = $agentId,
-      t.abandonedAt = timestamp(),
-      t.abandonReason = $reason,
-      t.abandonCount = COALESCE(t.abandonCount, 0) + 1
-
-  RETURN t.id as id,
-         t.title as title,
-         t.status as status,
-         t.abandonCount as abandonCount,
-         t.abandonReason as abandonReason
-`;
-/**
- * Query to force-start a task that's stuck in claimed state
- * Allows recovery when the normal start action fails
- */
-const FORCE_START_QUERY = `
-  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
-  WHERE t.claimedBy = $agentId
-    AND t.status IN ['claimed', 'available']
-
-  SET t.status = 'in_progress',
-      t.claimedBy = $agentId,
-      t.claimedAt = COALESCE(t.claimedAt, timestamp()),
-      t.startedAt = timestamp(),
-      t.updatedAt = timestamp(),
-      t.forceStarted = true,
-      t.forceStartReason = $reason
-
-  RETURN t.id as id,
-         t.title as title,
-         t.status as status,
-         t.claimedBy as claimedBy,
-         t.startedAt as startedAt,
-         t.forceStarted as forceStarted
-`;
-/**
- * Query to get current task state for better error messages
- */
-const GET_TASK_STATE_QUERY = `
-  MATCH (t:SwarmTask {id: $taskId, projectId: $projectId})
-  RETURN t.id as id,
-         t.title as title,
-         t.status as status,
-         t.claimedBy as claimedBy,
-         t.claimedAt as claimedAt,
-         t.startedAt as startedAt,
-         t.abandonCount as abandonCount,
-         t.previousClaimedBy as previousClaimedBy
-`;
 export const createSwarmClaimTaskTool = (server) => {
     server.registerTool(TOOL_NAMES.swarmClaimTask, {
         title: TOOL_METADATA[TOOL_NAMES.swarmClaimTask].title,
@@ -247,24 +24,14 @@ export const createSwarmClaimTaskTool = (server) => {
                 .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"])'),
+            types: z.array(z.enum(TASK_TYPES)).optional().describe('Filter by task types'),
             minPriority: z
                 .enum(Object.keys(TASK_PRIORITIES))
                 .optional()
-                .describe('Minimum priority level when auto-selecting'),
-            action: z
-                .enum(['claim', 'claim_and_start', 'start', 'release', 'abandon', 'force_start'])
-                .optional()
-                .default('claim_and_start')
-                .describe('Action: claim_and_start (RECOMMENDED: atomic claim+start), claim (reserve only), ' +
-                'start (begin work on claimed task), release (give up task), ' +
-                'abandon (release with tracking), force_start (recover from stuck claimed state)'),
-            releaseReason: z.string().optional().describe('Reason for releasing/abandoning the task'),
+                .describe('Minimum priority when auto-selecting'),
+            startImmediately: z.boolean().optional().default(true).describe('Start the task immediately after claiming'),
         },
-    }, async ({ projectId, swarmId, agentId, taskId, types, minPriority, action = 'claim_and_start', releaseReason }) => {
+    }, async ({ projectId, swarmId, agentId, taskId, types, minPriority, startImmediately = true }) => {
         const neo4jService = new Neo4jService();
         // Resolve project ID
         const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
@@ -274,160 +41,29 @@ export const createSwarmClaimTaskTool = (server) => {
         }
         const resolvedProjectId = projectResult.projectId;
         try {
-            // 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) {
-                    // Get current state for better error message
-                    const stateResult = await neo4jService.run(GET_TASK_STATE_QUERY, {
-                        taskId,
-                        projectId: resolvedProjectId,
-                    });
-                    const currentState = stateResult[0];
-                    return createErrorResponse(`Cannot release task ${taskId}. ` +
-                        (currentState
-                            ? `Current state: ${currentState.status}, claimedBy: ${currentState.claimedBy || 'none'}`
-                            : 'Task not found.'));
-                }
-                return createSuccessResponse(JSON.stringify({ action: 'released', taskId: result[0].id }));
-            }
-            // Handle abandon action (release with tracking)
-            if (action === 'abandon') {
-                if (!taskId) {
-                    return createErrorResponse('taskId is required for abandon action');
-                }
-                const result = await neo4jService.run(ABANDON_TASK_QUERY, {
-                    taskId,
-                    projectId: resolvedProjectId,
-                    agentId,
-                    reason: releaseReason || 'No reason provided',
-                });
-                if (result.length === 0) {
-                    const stateResult = await neo4jService.run(GET_TASK_STATE_QUERY, {
-                        taskId,
-                        projectId: resolvedProjectId,
-                    });
-                    const currentState = stateResult[0];
-                    return createErrorResponse(`Cannot abandon task ${taskId}. ` +
-                        (currentState
-                            ? `Current state: ${currentState.status}, claimedBy: ${currentState.claimedBy || 'none'}`
-                            : 'Task not found.'));
-                }
-                const abandonCount = typeof result[0].abandonCount === 'object' ? result[0].abandonCount.toNumber() : result[0].abandonCount;
-                return createSuccessResponse(JSON.stringify({ action: 'abandoned', taskId: result[0].id, abandonCount }));
-            }
-            // Handle force_start action (recovery from stuck claimed state)
-            if (action === 'force_start') {
-                if (!taskId) {
-                    return createErrorResponse('taskId is required for force_start action');
-                }
-                const result = await neo4jService.run(FORCE_START_QUERY, {
-                    taskId,
-                    projectId: resolvedProjectId,
-                    agentId,
-                    reason: releaseReason || 'Recovering from stuck state',
-                });
-                if (result.length === 0) {
-                    const stateResult = await neo4jService.run(GET_TASK_STATE_QUERY, {
-                        taskId,
-                        projectId: resolvedProjectId,
-                    });
-                    const currentState = stateResult[0];
-                    return createErrorResponse(`Cannot force_start task ${taskId}. ` +
-                        (currentState
-                            ? `Current state: ${currentState.status}, claimedBy: ${currentState.claimedBy || 'none'}. ` +
-                                `force_start requires status=claimed|available and you must be the claimant.`
-                            : 'Task not found.'));
-                }
-                return createSuccessResponse(JSON.stringify({ action: 'force_started', taskId: result[0].id, status: 'in_progress' }));
-            }
-            // 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) {
-                    // Get current state for better error message
-                    const stateResult = await neo4jService.run(GET_TASK_STATE_QUERY, {
-                        taskId,
-                        projectId: resolvedProjectId,
-                    });
-                    const currentState = stateResult[0];
-                    return createErrorResponse(`Cannot start task ${taskId}. ` +
-                        (currentState
-                            ? `Current state: ${currentState.status}, claimedBy: ${currentState.claimedBy || 'none'}. ` +
-                                `Tip: Use action="force_start" to recover from stuck claimed state, ` +
-                                `or action="abandon" to release the task.`
-                            : 'Task not found.'));
-                }
-                return createSuccessResponse(JSON.stringify({ action: 'started', taskId: result[0].id, status: 'in_progress' }));
-            }
-            // Handle claim and claim_and_start actions
-            // Determine target status based on action
-            const targetStatus = action === 'claim_and_start' ? 'in_progress' : 'claimed';
-            let result;
-            let retryCount = 0;
+            const claimHandler = new SwarmClaimHandler(neo4jService);
+            const targetStatus = startImmediately ? 'in_progress' : 'claimed';
+            let claimResult;
             if (taskId) {
-                // Claim specific task
-                result = await neo4jService.run(CLAIM_TASK_BY_ID_QUERY, {
-                    taskId,
-                    projectId: resolvedProjectId,
-                    agentId,
-                    targetStatus,
-                });
-                if (result.length === 0) {
-                    const stateResult = await neo4jService.run(GET_TASK_STATE_QUERY, {
-                        taskId,
-                        projectId: resolvedProjectId,
-                    });
-                    const currentState = stateResult[0];
+                claimResult = await claimHandler.claimById(resolvedProjectId, taskId, agentId, targetStatus);
+                if (claimResult.error) {
                     return createErrorResponse(`Cannot claim task ${taskId}. ` +
-                        (currentState
-                            ? `Current state: ${currentState.status}, claimedBy: ${currentState.claimedBy || 'none'}`
+                        (claimResult.data
+                            ? `Current state: ${claimResult.data.status}, claimedBy: ${claimResult.data.claimedBy || 'none'}`
                             : 'Task not found or has incomplete dependencies.'));
                 }
             }
             else {
-                // Auto-select highest priority available task with retry logic
-                const minPriorityScore = minPriority ? TASK_PRIORITIES[minPriority] : null;
-                // Retry loop to handle race conditions
-                while (retryCount < MAX_CLAIM_RETRIES) {
-                    result = await neo4jService.run(CLAIM_NEXT_TASK_QUERY, {
-                        projectId: resolvedProjectId,
-                        swarmId,
-                        agentId,
-                        types: types || null,
-                        minPriority: minPriorityScore,
-                        targetStatus,
-                    });
-                    if (result.length > 0) {
-                        break; // Successfully claimed a task
-                    }
-                    retryCount++;
-                    if (retryCount < MAX_CLAIM_RETRIES) {
-                        // Wait before retry with exponential backoff
-                        await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_BASE_MS * Math.pow(2, retryCount - 1)));
-                    }
-                }
-                if (!result || result.length === 0) {
-                    return createSuccessResponse(JSON.stringify({ action: 'no_tasks', retryAttempts: retryCount }));
+                claimResult = await claimHandler.claimNext(resolvedProjectId, swarmId, agentId, targetStatus, {
+                    types: types || null,
+                    minPriority: minPriority || null,
+                });
+                if (!claimResult.data) {
+                    return createEmptyResponse('No available tasks matching criteria', 'Check swarm_get_tasks for task statuses, or post new tasks with swarm_post_task.');
                 }
             }
-            const task = result[0];
-            const actionLabel = action === 'claim_and_start' ? 'claimed_and_started' : 'claimed';
+            const task = claimResult.data;
+            const actionLabel = startImmediately ? 'claimed_and_started' : 'claimed';
             // Extract valid targets (resolved via :TARGETS relationship)
             const resolvedTargets = (task.targets || [])
                 .filter((t) => t?.id)
@@ -485,7 +121,7 @@ export const createSwarmClaimTaskTool = (server) => {
                     ...(task.dependencies?.length > 0 && { dependencies: task.dependencies }),
                 },
                 ...(pendingMessages.length > 0 && { messages: pendingMessages }),
-                ...(retryCount > 0 && { retryAttempts: retryCount }),
+                ...(claimResult.retryAttempts > 0 && { retryAttempts: claimResult.retryAttempts }),
             }));
         }
         catch (error) {

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

@@ -99,17 +99,13 @@ export const createSwarmCleanupTool = (server) => {
             projectId: z.string().describe('Project ID, name, or path'),
             swarmId: z.string().optional().describe('Delete all pheromones and tasks from this swarm'),
             agentId: z.string().optional().describe('Delete all pheromones from this agent'),
-            all: z.boolean().optional().default(false).describe('Delete ALL pheromones in project (use with caution)'),
+            all: z.boolean().optional().default(false).describe('Delete ALL pheromones in project'),
             includeTasks: z
                 .boolean()
                 .optional()
                 .default(true)
-                .describe('Also delete SwarmTask nodes (default: true, only applies when swarmId is provided)'),
-            keepTypes: z
-                .array(z.string())
-                .optional()
-                .default(['warning'])
-                .describe('Pheromone types to preserve (default: ["warning"])'),
+                .describe('Also delete SwarmTask nodes (only applies when swarmId is provided)'),
+            keepTypes: z.array(z.string()).optional().default(['warning']).describe('Pheromone types to preserve'),
             dryRun: z.boolean().optional().default(false).describe('Preview what would be deleted without deleting'),
         },
     }, async ({ projectId, swarmId, agentId, all = false, includeTasks = true, keepTypes = ['warning'], dryRun = false, }) => {

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

@@ -214,7 +214,7 @@ async function getTaskStateError(neo4jService, taskId, projectId, action, agentI
     let suggestion = '';
     if (action === 'complete' || action === 'fail') {
         if (state.status === 'available') {
-            suggestion = 'You must claim the task first using swarm_claim_task.';
+            suggestion = 'You must claim the task first using swarm_claim_task, then start it or use startImmediately=true.';
         }
         else if (!isOwner) {
             suggestion = `Task is claimed by "${claimedBy}", not you.`;
@@ -245,29 +245,26 @@ export const createSwarmCompleteTaskTool = (server) => {
         inputSchema: {
             projectId: z.string().describe('Project ID, name, or path'),
             taskId: z.string().describe('Task ID to complete'),
-            agentId: z.string().describe('Your agent ID (must match the agent who claimed the task)'),
+            agentId: z.string().describe('Your agent ID (must match who claimed the task)'),
             action: z
                 .enum(['complete', 'fail', 'request_review', 'approve', 'reject', 'retry'])
                 .describe('Action to take on the task'),
-            summary: z.string().optional().describe('Summary of what was done (required for complete/request_review)'),
-            artifacts: z
-                .record(z.unknown())
-                .optional()
-                .describe('Artifacts produced: { files: [], commits: [], pullRequests: [], notes: string }'),
-            filesChanged: z.array(z.string()).optional().describe('List of files that were modified'),
-            linesAdded: z.number().int().optional().describe('Number of lines added'),
-            linesRemoved: z.number().int().optional().describe('Number of lines removed'),
-            reason: z.string().optional().describe('Reason for failure (required if action=fail)'),
-            errorDetails: z.string().optional().describe('Technical error details for debugging'),
-            retryable: z.boolean().optional().default(true).describe('Whether the task can be retried after failure'),
-            reviewNotes: z.string().optional().describe('Notes for the reviewer (for request_review)'),
-            reviewerId: z.string().optional().describe('ID of the reviewer (required for approve/reject)'),
-            notes: z.string().optional().describe('Approval/rejection notes'),
+            summary: z.string().optional().describe('What was done (required for complete/request_review)'),
+            artifacts: z.record(z.unknown()).optional().describe('Artifacts produced by this task'),
+            filesChanged: z.array(z.string()).optional().describe('Files modified'),
+            linesAdded: z.number().int().optional().describe('Lines added'),
+            linesRemoved: z.number().int().optional().describe('Lines removed'),
+            reason: z.string().optional().describe('Failure reason (required for action=fail)'),
+            errorDetails: z.string().optional().describe('Technical error details'),
+            retryable: z.boolean().optional().default(true).describe('Allow retry after failure'),
+            reviewNotes: z.string().optional().describe('Notes for the reviewer'),
+            reviewerId: z.string().optional().describe('Reviewer ID (required for approve/reject)'),
+            notes: z.string().optional().describe('Approval or rejection notes'),
             markAsFailed: z
                 .boolean()
                 .optional()
                 .default(false)
-                .describe('If rejecting, mark as failed instead of returning to in_progress'),
+                .describe('On reject, mark as failed instead of returning to in_progress'),
         },
     }, async ({ projectId, taskId, agentId, action, summary, artifacts, filesChanged, linesAdded, linesRemoved, reason, errorDetails, retryable = true, reviewNotes, reviewerId, notes, markAsFailed = false, }) => {
         const neo4jService = new Neo4jService();

package/dist/mcp/tools/swarm-get-tasks.tool.js

@@ -163,41 +163,23 @@ export const createSwarmGetTasksTool = (server) => {
             projectId: z.string().describe('Project ID, name, or path'),
             swarmId: z.string().optional().describe('Filter by swarm ID'),
             taskId: z.string().optional().describe('Get a specific task by ID (returns full details)'),
-            statuses: z
-                .array(z.enum(TASK_STATUSES))
-                .optional()
-                .describe('Filter by task statuses (e.g., ["available", "in_progress"])'),
-            types: z.array(z.enum(TASK_TYPES)).optional().describe('Filter by task types (e.g., ["implement", "fix"])'),
-            claimedBy: z.string().optional().describe('Filter tasks claimed by a specific agent'),
-            createdBy: z.string().optional().describe('Filter tasks created by a specific agent'),
+            statuses: z.array(z.enum(TASK_STATUSES)).optional().describe('Filter by task statuses'),
+            types: z.array(z.enum(TASK_TYPES)).optional().describe('Filter by task types'),
+            claimedBy: z.string().optional().describe('Filter by claiming agent'),
+            createdBy: z.string().optional().describe('Filter by creating agent'),
             minPriority: z
                 .enum(Object.keys(TASK_PRIORITIES))
                 .optional()
                 .describe('Minimum priority level'),
-            orderBy: z
-                .enum(['priority', 'created', 'updated'])
-                .optional()
-                .default('priority')
-                .describe('Sort order: priority (highest first), created (newest first), updated'),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .default(20)
-                .describe('Maximum tasks to return (default: 20)'),
-            skip: z.number().int().min(0).optional().default(0).describe('Number of tasks to skip for pagination'),
+            orderBy: z.enum(['priority', 'created', 'updated']).optional().default('priority').describe('Sort order'),
+            limit: z.number().int().min(1).max(100).optional().default(20).describe('Maximum tasks to return'),
+            skip: z.number().int().min(0).optional().default(0).describe('Tasks to skip for pagination'),
             includeStats: z
                 .boolean()
                 .optional()
                 .default(false)
                 .describe('Include aggregate statistics by status/type/agent'),
-            includeDependencyGraph: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe('Include dependency graph for visualization'),
+            includeDependencyGraph: z.boolean().optional().default(false).describe('Include dependency graph'),
         },
     }, async ({ projectId, swarmId, taskId, statuses, types, claimedBy, createdBy, minPriority, orderBy = 'priority', limit = 20, skip = 0, includeStats = false, includeDependencyGraph = false, }) => {
         const neo4jService = new Neo4jService();

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

@@ -162,39 +162,24 @@ export const createSwarmMessageTool = (server) => {
             agentId: z.string().describe('Your unique agent identifier'),
             action: z
                 .enum(['send', 'read', 'acknowledge'])
-                .describe('Action: send (post message), read (get messages), acknowledge (mark as read)'),
+                .describe('send: post message; read: get messages; acknowledge: mark as read'),
             // Send parameters
-            toAgentId: z.string().optional().describe('Target agent ID. Omit for broadcast to all swarm agents.'),
-            category: z
-                .enum(MESSAGE_CATEGORY_KEYS)
-                .optional()
-                .describe('Message category: blocked (need help), conflict (resource clash), finding (important discovery), ' +
-                'request (direct ask), alert (urgent notification), handoff (context transfer)'),
-            content: z.string().optional().describe('Message content (required for send action)'),
-            taskId: z.string().optional().describe('Related task ID for context'),
+            toAgentId: z.string().optional().describe('Target agent ID (omit for broadcast)'),
+            category: z.enum(MESSAGE_CATEGORY_KEYS).optional().describe('Message category'),
+            content: z.string().optional().describe('Message content (required for send)'),
+            taskId: z.string().optional().describe('Related task ID'),
             filePaths: z.array(z.string()).optional().describe('File paths relevant to this message'),
-            ttlMs: z
-                .number()
-                .int()
-                .optional()
-                .describe(`Time-to-live in ms (default: ${MESSAGE_DEFAULT_TTL_MS / 3600000}h). Set 0 for swarm lifetime.`),
+            ttlMs: z.number().int().optional().describe(`Time-to-live in ms (0 for swarm lifetime)`),
             // Read parameters
-            unreadOnly: z.boolean().optional().default(true).describe('Only return unread messages (default: true)'),
+            unreadOnly: z.boolean().optional().default(true).describe('Only return unread messages'),
             categories: z.array(z.enum(MESSAGE_CATEGORY_KEYS)).optional().describe('Filter by message categories'),
-            fromAgentId: z.string().optional().describe('Filter messages from a specific agent'),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .default(20)
-                .describe('Maximum messages to return (default: 20)'),
+            fromAgentId: z.string().optional().describe('Filter by sending agent'),
+            limit: z.number().int().min(1).max(100).optional().default(20).describe('Maximum messages to return'),
             // Acknowledge parameters
             messageIds: z
                 .array(z.string())
                 .optional()
-                .describe('Specific message IDs to acknowledge. Omit to acknowledge all unread.'),
+                .describe('Message IDs to acknowledge (omit to acknowledge all unread)'),
             // Maintenance
             cleanup: z.boolean().optional().default(false).describe('Also clean up expired messages'),
         },