@taazkareem/clickup-mcp-server 0.6.8 → 0.6.9

package/build/services/clickup/task.js

@@ -0,0 +1,976 @@
+/**
+ * SPDX-FileCopyrightText: © 2025 Talib Kareem <taazkareem@icloud.com>
+ * SPDX-License-Identifier: MIT
+ *
+ * ClickUp Task Service
+ *
+ * Handles all operations related to tasks in ClickUp, including:
+ * - Creating tasks (single and bulk)
+ * - Retrieving tasks (single or multiple)
+ * - Updating tasks
+ * - Deleting tasks
+ * - Finding tasks by name
+ */
+import { BaseClickUpService, ErrorCode, ClickUpServiceError } from './base.js';
+import { ListService } from './list.js';
+import { estimateTokensFromObject, wouldExceedTokenLimit } from '../../utils/token-utils.js';
+import { isNameMatch } from '../../utils/resolver-utils.js';
+import { findListIDByName } from '../../tools/list.js';
+export class TaskService extends BaseClickUpService {
+    constructor(apiKey, teamId, baseUrl, workspaceService) {
+        super(apiKey, teamId, baseUrl);
+        this.workspaceService = null;
+        if (workspaceService) {
+            this.workspaceService = workspaceService;
+            this.logOperation('constructor', { usingSharedWorkspaceService: true });
+        }
+        // Initialize list service for list lookups
+        this.listService = new ListService(apiKey, teamId, baseUrl, this.workspaceService);
+        this.logOperation('constructor', { initialized: true });
+    }
+    /**
+     * Helper method to handle errors consistently
+     * @param error The error that occurred
+     * @param message Optional custom error message
+     * @returns A ClickUpServiceError
+     */
+    handleError(error, message) {
+        if (error instanceof ClickUpServiceError) {
+            return error;
+        }
+        return new ClickUpServiceError(message || `Task service error: ${error.message}`, ErrorCode.UNKNOWN, error);
+    }
+    /**
+     * Build URL parameters from task filters
+     * @param filters Task filters to convert to URL parameters
+     * @returns URLSearchParams object
+     */
+    buildTaskFilterParams(filters) {
+        const params = new URLSearchParams();
+        // Add all filters to the query parameters
+        if (filters.include_closed)
+            params.append('include_closed', String(filters.include_closed));
+        if (filters.subtasks)
+            params.append('subtasks', String(filters.subtasks));
+        if (filters.page)
+            params.append('page', String(filters.page));
+        if (filters.order_by)
+            params.append('order_by', filters.order_by);
+        if (filters.reverse)
+            params.append('reverse', String(filters.reverse));
+        // Array parameters
+        if (filters.statuses && filters.statuses.length > 0) {
+            filters.statuses.forEach(status => params.append('statuses[]', status));
+        }
+        if (filters.assignees && filters.assignees.length > 0) {
+            filters.assignees.forEach(assignee => params.append('assignees[]', assignee));
+        }
+        // Team tasks endpoint specific parameters
+        if (filters.tags && filters.tags.length > 0) {
+            filters.tags.forEach(tag => params.append('tags[]', tag));
+        }
+        if (filters.list_ids && filters.list_ids.length > 0) {
+            filters.list_ids.forEach(id => params.append('list_ids[]', id));
+        }
+        if (filters.folder_ids && filters.folder_ids.length > 0) {
+            filters.folder_ids.forEach(id => params.append('folder_ids[]', id));
+        }
+        if (filters.space_ids && filters.space_ids.length > 0) {
+            filters.space_ids.forEach(id => params.append('space_ids[]', id));
+        }
+        if (filters.archived !== undefined)
+            params.append('archived', String(filters.archived));
+        if (filters.include_closed_lists !== undefined)
+            params.append('include_closed_lists', String(filters.include_closed_lists));
+        if (filters.include_archived_lists !== undefined)
+            params.append('include_archived_lists', String(filters.include_archived_lists));
+        if (filters.include_compact_time_entries !== undefined)
+            params.append('include_compact_time_entries', String(filters.include_compact_time_entries));
+        // Date filters
+        if (filters.due_date_gt)
+            params.append('due_date_gt', String(filters.due_date_gt));
+        if (filters.due_date_lt)
+            params.append('due_date_lt', String(filters.due_date_lt));
+        if (filters.date_created_gt)
+            params.append('date_created_gt', String(filters.date_created_gt));
+        if (filters.date_created_lt)
+            params.append('date_created_lt', String(filters.date_created_lt));
+        if (filters.date_updated_gt)
+            params.append('date_updated_gt', String(filters.date_updated_gt));
+        if (filters.date_updated_lt)
+            params.append('date_updated_lt', String(filters.date_updated_lt));
+        // Handle custom fields if present
+        if (filters.custom_fields) {
+            Object.entries(filters.custom_fields).forEach(([key, value]) => {
+                params.append(`custom_fields[${key}]`, String(value));
+            });
+        }
+        return params;
+    }
+    /**
+     * Extract priority value from a task
+     * @param task The task to extract priority from
+     * @returns TaskPriority or null
+     */
+    extractPriorityValue(task) {
+        if (!task.priority || !task.priority.id) {
+            return null;
+        }
+        const priorityValue = parseInt(task.priority.id);
+        // Ensure it's in the valid range 1-4
+        if (isNaN(priorityValue) || priorityValue < 1 || priorityValue > 4) {
+            return null;
+        }
+        return priorityValue;
+    }
+    /**
+     * Extract task data for creation/duplication
+     * @param task The source task
+     * @param nameOverride Optional override for the task name
+     * @returns CreateTaskData object
+     */
+    extractTaskData(task, nameOverride) {
+        return {
+            name: nameOverride || task.name,
+            description: task.description || '',
+            status: task.status?.status,
+            priority: this.extractPriorityValue(task),
+            due_date: task.due_date ? Number(task.due_date) : undefined,
+            assignees: task.assignees?.map(a => a.id) || []
+        };
+    }
+    /**
+     * Create a new task in the specified list
+     * @param listId The ID of the list to create the task in
+     * @param taskData The data for the new task
+     * @returns The created task
+     */
+    async createTask(listId, taskData) {
+        this.logOperation('createTask', { listId, ...taskData });
+        try {
+            return await this.makeRequest(async () => {
+                const response = await this.client.post(`/list/${listId}/task`, taskData);
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to create task in list ${listId}`);
+        }
+    }
+    /**
+     * Get all tasks in a list with optional filtering
+     * @param listId The ID of the list to get tasks from
+     * @param filters Optional filters to apply
+     * @returns List of tasks matching the filters
+     */
+    async getTasks(listId, filters = {}) {
+        this.logOperation('getTasks', { listId, filters });
+        try {
+            return await this.makeRequest(async () => {
+                const params = this.buildTaskFilterParams(filters);
+                const response = await this.client.get(`/list/${listId}/task?${params.toString()}`);
+                return response.data.tasks;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get tasks from list ${listId}`);
+        }
+    }
+    /**
+     * Get a specific task by ID
+     * @param taskId The ID of the task to retrieve
+     * @returns The task details
+     */
+    async getTask(taskId) {
+        this.logOperation('getTask', { taskId });
+        try {
+            return await this.makeRequest(async () => {
+                const response = await this.client.get(`/task/${taskId}`);
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get task ${taskId}`);
+        }
+    }
+    /**
+     * Get subtasks of a specific task
+     * @param taskId The ID of the parent task
+     * @returns Array of subtask details
+     */
+    async getSubtasks(taskId) {
+        this.logOperation('getSubtasks', { taskId });
+        try {
+            return await this.makeRequest(async () => {
+                // First, get the task to get its list ID
+                const task = await this.getTask(taskId);
+                const listId = task.list.id;
+                // Then get all tasks from the list
+                const allTasks = await this.getTasks(listId, { subtasks: true });
+                // Filter tasks that have the specified task as parent
+                return allTasks.filter(t => t.parent === taskId || t.top_level_parent === taskId);
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to get subtasks of task ${taskId}`);
+        }
+    }
+    /**
+     * Get a specific task by its custom ID
+     * @param customTaskId The custom ID of the task (e.g., "DEV-1234")
+     * @param listId Optional list ID to search within for better performance
+     * @returns The task details
+     */
+    async getTaskByCustomId(customTaskId, listId) {
+        this.logOperation('getTaskByCustomId', { customTaskId, listId });
+        try {
+            return await this.makeRequest(async () => {
+                // Build query with custom_task_ids=true and team_id
+                const params = new URLSearchParams({
+                    custom_task_ids: 'true',
+                    team_id: this.teamId
+                });
+                // Use the ClickUp API endpoint for retrieving tasks by ID
+                // With custom_task_ids=true parameter, it will treat the ID as a custom ID
+                const response = await this.client.get(`/task/${customTaskId}?${params.toString()}`);
+                return response.data;
+            });
+        }
+        catch (error) {
+            // Enhance error message for custom ID lookups
+            if (error?.response?.status === 404) {
+                throw this.handleError(error, `Task with custom ID ${customTaskId} not found`);
+            }
+            throw this.handleError(error, `Failed to get task with custom ID ${customTaskId}`);
+        }
+    }
+    /**
+     * Update an existing task
+     * @param taskId ID of the task to update
+     * @param updateData Data to update on the task
+     * @returns The updated task
+     */
+    async updateTask(taskId, updateData) {
+        this.logOperation('updateTask', { taskId, ...updateData });
+        try {
+            return await this.makeRequest(async () => {
+                const response = await this.client.put(`/task/${taskId}`, updateData);
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to update task ${taskId}`);
+        }
+    }
+    /**
+     * Delete a task
+     * @param taskId The ID of the task to delete
+     * @returns Success indicator
+     */
+    async deleteTask(taskId) {
+        this.logOperation('deleteTask', { taskId });
+        try {
+            await this.makeRequest(async () => {
+                await this.client.delete(`/task/${taskId}`);
+            });
+            return {
+                success: true
+            };
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to delete task ${taskId}`);
+        }
+    }
+    /**
+     * Find a task by name within a list
+     * @param listId The list ID to search within
+     * @param taskName The name of the task to find
+     * @returns The task if found, otherwise null
+     */
+    async findTaskByName(listId, taskName) {
+        this.logOperation('findTaskByName', { listId, taskName });
+        try {
+            const tasks = await this.getTasks(listId);
+            // Find task by exact match first, then case-insensitive, then substring
+            // Exact match
+            let match = tasks.find(task => task.name === taskName);
+            if (match)
+                return match;
+            // Case-insensitive match
+            match = tasks.find(task => task.name.toLowerCase() === taskName.toLowerCase());
+            if (match)
+                return match;
+            // Substring match
+            match = tasks.find(task => task.name.toLowerCase().includes(taskName.toLowerCase()));
+            return match || null;
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to find task by name: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Move a task to a different list
+     * @param taskId The ID of the task to move
+     * @param destinationListId The ID of the list to move the task to
+     * @returns The updated task
+     */
+    async moveTask(taskId, destinationListId) {
+        this.logOperation('moveTask', { taskId, destinationListId });
+        try {
+            // First, get both the task and list info in parallel to save time
+            const [originalTask, destinationList] = await Promise.all([
+                this.getTask(taskId),
+                this.listService.getList(destinationListId)
+            ]);
+            const currentStatus = originalTask.status?.status;
+            const availableStatuses = destinationList.statuses?.map(s => s.status) || [];
+            // Determine the appropriate status for the destination list
+            let newStatus = availableStatuses.includes(currentStatus || '')
+                ? currentStatus // Keep the same status if available in destination list
+                : destinationList.statuses?.[0]?.status; // Otherwise use the default (first) status
+            // Prepare the task data for the new list
+            const taskData = this.extractTaskData(originalTask);
+            taskData.status = newStatus;
+            // Create new task and delete old one in a single makeRequest call
+            return await this.makeRequest(async () => {
+                // First create the new task
+                const response = await this.client.post(`/list/${destinationListId}/task`, taskData);
+                // Then delete the original task
+                await this.client.delete(`/task/${taskId}`);
+                // Add a property to indicate the task was moved
+                const newTask = {
+                    ...response.data,
+                    moved: true,
+                    originalId: taskId
+                };
+                return newTask;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to move task');
+        }
+    }
+    /**
+     * Create a duplicate of an existing task
+     * @param taskId The ID of the task to duplicate
+     * @param listId Optional destination list ID (defaults to the same list)
+     * @returns The newly created duplicate task
+     */
+    async duplicateTask(taskId, listId) {
+        this.logOperation('duplicateTask', { taskId, listId });
+        try {
+            // Get the original task to duplicate
+            const originalTask = await this.getTask(taskId);
+            // Create a copy of the task data with "(copy)" appended to the name
+            const newTaskData = this.extractTaskData(originalTask, `${originalTask.name} (copy)`);
+            // Create the new task in the specified list or original list
+            const targetListId = listId || originalTask.list.id;
+            return await this.createTask(targetListId, newTaskData);
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to duplicate task');
+        }
+    }
+    /**
+     * Get all comments for a task
+     *
+     * @param taskId ID of the task to get comments for
+     * @param start Optional pagination start
+     * @param startId Optional comment ID to start from
+     * @returns Array of task comments
+     */
+    async getTaskComments(taskId, start, startId) {
+        this.logOperation('getTaskComments', { taskId, start, startId });
+        try {
+            // Build query parameters for pagination
+            const queryParams = new URLSearchParams();
+            if (start !== undefined) {
+                queryParams.append('start', start.toString());
+            }
+            if (startId) {
+                queryParams.append('start_id', startId);
+            }
+            const queryString = queryParams.toString() ? `?${queryParams.toString()}` : '';
+            const response = await this.client.get(`/task/${taskId}/comment${queryString}`);
+            return response.data.comments || [];
+        }
+        catch (error) {
+            throw this.handleError(error, 'Failed to get task comments');
+        }
+    }
+    /**
+     * Create a comment on a task
+     *
+     * @param taskId ID of the task to comment on
+     * @param commentText Text content of the comment
+     * @param notifyAll Whether to notify all assignees
+     * @param assignee Optional user ID to assign the comment to
+     * @returns The created comment
+     */
+    async createTaskComment(taskId, commentText, notifyAll = false, assignee) {
+        this.logOperation('createTaskComment', { taskId, commentText, notifyAll, assignee });
+        try {
+            const payload = {
+                comment_text: commentText,
+                notify_all: notifyAll
+            };
+            if (assignee) {
+                payload.assignee = assignee;
+            }
+            // Make the request directly without using makeRequest for better error handling
+            const response = await this.client.post(`/task/${taskId}/comment`, payload);
+            // Handle different response formats from ClickUp API
+            if (response.data) {
+                if (response.data.comment) {
+                    // Standard format: { comment: ClickUpComment }
+                    return response.data.comment;
+                }
+                else if (response.data.id && (response.data.comment_text || response.data.comment)) {
+                    // Direct format: the comment object itself
+                    return response.data;
+                }
+                else {
+                    // Fallback: construct a minimal valid comment object
+                    return {
+                        id: response.data.id || `custom-${Date.now()}`,
+                        comment: response.data.comment || commentText,
+                        comment_text: response.data.comment_text || commentText,
+                        user: response.data.user || { id: 0, username: 'Unknown', email: '', color: '' },
+                        date: response.data.date || new Date().toISOString(),
+                        resolved: false
+                    };
+                }
+            }
+            throw new Error('Invalid response from ClickUp API');
+        }
+        catch (error) {
+            // Check if comment might have been created despite error
+            if (error.response?.status === 200 || error.response?.status === 201) {
+                // Try to construct a comment object from what we know
+                return {
+                    id: `fallback-${Date.now()}`,
+                    comment: commentText,
+                    comment_text: commentText,
+                    user: { id: 0, username: 'Unknown', email: '', color: '' },
+                    date: new Date().toISOString(),
+                    resolved: false
+                };
+            }
+            throw this.handleError(error, 'Failed to create task comment');
+        }
+    }
+    /**
+     * Validate that a list exists
+     *
+     * @param listId ID of the list to validate
+     * @throws ClickUpServiceError if the list doesn't exist
+     */
+    async validateListExists(listId) {
+        this.logOperation('validateListExists', { listId });
+        try {
+            const list = await this.listService.getList(listId);
+            if (!list) {
+                throw new ClickUpServiceError(`List not found: ${listId}`, ErrorCode.NOT_FOUND, { listId });
+            }
+        }
+        catch (error) {
+            if (error instanceof ClickUpServiceError) {
+                throw error;
+            }
+            throw new ClickUpServiceError(`Failed to validate list existence: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.UNKNOWN, { listId });
+        }
+    }
+    /**
+     * Upload a file attachment to a ClickUp task
+     * @param taskId The ID of the task to attach the file to
+     * @param fileData The file data as a Buffer
+     * @param fileName The name of the file
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachment(taskId, fileData, fileName) {
+        this.logOperation('uploadTaskAttachment', { taskId, fileName, fileSize: fileData.length });
+        try {
+            return await this.makeRequest(async () => {
+                // Create FormData for multipart/form-data upload
+                const FormData = (await import('form-data')).default;
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', fileData, {
+                    filename: fileName,
+                    contentType: 'application/octet-stream' // Let ClickUp determine the content type
+                });
+                // Use the raw axios client for this request since we need to handle FormData
+                const response = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return response.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment to task ${taskId}`);
+        }
+    }
+    /**
+     * Upload a file attachment to a ClickUp task from a URL
+     * @param taskId The ID of the task to attach the file to
+     * @param fileUrl The URL of the file to download and attach
+     * @param fileName Optional file name (if not provided, it will be extracted from the URL)
+     * @param authHeader Optional authorization header for the URL
+     * @returns Promise resolving to the attachment response from ClickUp
+     */
+    async uploadTaskAttachmentFromUrl(taskId, fileUrl, fileName, authHeader) {
+        this.logOperation('uploadTaskAttachmentFromUrl', { taskId, fileUrl, fileName });
+        try {
+            return await this.makeRequest(async () => {
+                // Import required modules
+                const axios = (await import('axios')).default;
+                const FormData = (await import('form-data')).default;
+                // Download the file from the URL
+                const headers = {};
+                if (authHeader) {
+                    headers['Authorization'] = authHeader;
+                }
+                const response = await axios.get(fileUrl, {
+                    responseType: 'arraybuffer',
+                    headers
+                });
+                // Extract filename from URL if not provided
+                const actualFileName = fileName || fileUrl.split('/').pop() || 'downloaded-file';
+                // Create FormData for multipart/form-data upload
+                const formData = new FormData();
+                // Add the file to the form data
+                formData.append('attachment', Buffer.from(response.data), {
+                    filename: actualFileName,
+                    contentType: 'application/octet-stream'
+                });
+                // Upload the file to ClickUp
+                const uploadResponse = await this.client.post(`/task/${taskId}/attachment`, formData, {
+                    headers: {
+                        ...formData.getHeaders(),
+                        'Authorization': this.apiKey
+                    }
+                });
+                return uploadResponse.data;
+            });
+        }
+        catch (error) {
+            throw this.handleError(error, `Failed to upload attachment from URL to task ${taskId}`);
+        }
+    }
+    /**
+     * Format task data for summary view
+     * @param task The task to format
+     * @returns TaskSummary object
+     */
+    formatTaskSummary(task) {
+        return {
+            id: task.id,
+            name: task.name,
+            status: task.status.status,
+            list: {
+                id: task.list.id,
+                name: task.list.name
+            },
+            due_date: task.due_date,
+            url: task.url,
+            priority: this.extractPriorityValue(task),
+            tags: task.tags.map(tag => ({
+                name: tag.name,
+                tag_bg: tag.tag_bg,
+                tag_fg: tag.tag_fg
+            }))
+        };
+    }
+    /**
+     * Estimates token count for a task in JSON format
+     * @param task ClickUp task
+     * @returns Estimated token count
+     */
+    estimateTaskTokens(task) {
+        return estimateTokensFromObject(task);
+    }
+    /**
+     * Get filtered tasks across the entire team/workspace using tags and other filters
+     * @param filters Task filters to apply including tags, list/folder/space filtering
+     * @returns Either a DetailedTaskResponse or WorkspaceTasksResponse depending on detail_level
+     */
+    async getWorkspaceTasks(filters = {}) {
+        try {
+            this.logOperation('getWorkspaceTasks', { filters });
+            const params = this.buildTaskFilterParams(filters);
+            const response = await this.client.get(`/team/${this.teamId}/task`, {
+                params
+            });
+            const tasks = response.data.tasks;
+            const totalCount = tasks.length; // Note: This is just the current page count
+            const hasMore = totalCount === 100; // ClickUp returns max 100 tasks per page
+            const nextPage = (filters.page || 0) + 1;
+            // If the estimated token count exceeds 50,000 or detail_level is 'summary',
+            // return summary format for efficiency and to avoid hitting token limits
+            const TOKEN_LIMIT = 50000;
+            // Estimate tokens for the full response
+            let tokensExceedLimit = false;
+            if (filters.detail_level !== 'summary' && tasks.length > 0) {
+                // We only need to check token count if detailed was requested
+                // For summary requests, we always return summary format
+                // First check with a sample task - if one task exceeds the limit, we definitely need summary
+                const sampleTask = tasks[0];
+                // Check if all tasks would exceed the token limit
+                const estimatedTokensPerTask = this.estimateTaskTokens(sampleTask);
+                const estimatedTotalTokens = estimatedTokensPerTask * tasks.length;
+                // Add 10% overhead for the response wrapper
+                tokensExceedLimit = estimatedTotalTokens * 1.1 > TOKEN_LIMIT;
+                // Double-check with more precise estimation if we're close to the limit
+                if (!tokensExceedLimit && estimatedTotalTokens * 1.1 > TOKEN_LIMIT * 0.8) {
+                    // More precise check - build a representative sample and extrapolate
+                    tokensExceedLimit = wouldExceedTokenLimit({ tasks, total_count: totalCount, has_more: hasMore, next_page: nextPage }, TOKEN_LIMIT);
+                }
+            }
+            // Determine if we should return summary or detailed based on request and token limit
+            const shouldUseSummary = filters.detail_level === 'summary' || tokensExceedLimit;
+            this.logOperation('getWorkspaceTasks', {
+                totalTasks: tasks.length,
+                estimatedTokens: tasks.reduce((count, task) => count + this.estimateTaskTokens(task), 0),
+                usingDetailedFormat: !shouldUseSummary,
+                requestedFormat: filters.detail_level || 'auto'
+            });
+            if (shouldUseSummary) {
+                return {
+                    summaries: tasks.map(task => this.formatTaskSummary(task)),
+                    total_count: totalCount,
+                    has_more: hasMore,
+                    next_page: nextPage
+                };
+            }
+            return {
+                tasks,
+                total_count: totalCount,
+                has_more: hasMore,
+                next_page: nextPage
+            };
+        }
+        catch (error) {
+            this.logOperation('getWorkspaceTasks', { error: error.message, status: error.response?.status });
+            throw this.handleError(error, 'Failed to get workspace tasks');
+        }
+    }
+    /**
+     * Get task summaries for lightweight retrieval
+     * @param filters Task filters to apply
+     * @returns WorkspaceTasksResponse with task summaries
+     */
+    async getTaskSummaries(filters = {}) {
+        return this.getWorkspaceTasks({ ...filters, detail_level: 'summary' });
+    }
+    /**
+     * Get detailed task data
+     * @param filters Task filters to apply
+     * @returns DetailedTaskResponse with full task data
+     */
+    async getTaskDetails(filters = {}) {
+        return this.getWorkspaceTasks({ ...filters, detail_level: 'detailed' });
+    }
+    /**
+     * Unified method for finding tasks by ID or name with consistent handling of global lookup
+     *
+     * This method provides a single entry point for all task lookup operations:
+     * - Direct lookup by task ID (regular or custom)
+     *   - Lookup by task name within a specific list
+     *   - Global lookup by task name across the entire workspace
+     *
+     * @param options Lookup options with the following parameters:
+     *   - taskId: Optional task ID for direct lookup
+     *   - customTaskId: Optional custom task ID for direct lookup
+     *   - taskName: Optional task name to search for
+     *   - listId: Optional list ID to scope the search
+     *   - listName: Optional list name to scope the search
+     *   - allowMultipleMatches: Whether to return all matches instead of throwing an error
+     *   - useSmartDisambiguation: Whether to automatically select the most recently updated task
+     *   - includeFullDetails: Whether to include full task details (true) or just task summaries (false)
+     *   - includeListContext: Whether to include list/folder/space context with results
+     * @returns Either a single task or an array of tasks depending on options
+     * @throws Error if task cannot be found or if multiple matches are found when not allowed
+     */
+    async findTasks({ taskId, customTaskId, taskName, listId, listName, allowMultipleMatches = false, useSmartDisambiguation = false, includeFullDetails = true, includeListContext = true }) {
+        try {
+            this.logOperation('findTasks', {
+                taskId,
+                customTaskId,
+                taskName,
+                listId,
+                listName,
+                allowMultipleMatches,
+                useSmartDisambiguation
+            });
+            // Case 1: Direct task ID lookup (highest priority)
+            if (taskId) {
+                // Check if it looks like a custom ID
+                if (taskId.includes('-') && /^[A-Z]+\-\d+$/.test(taskId)) {
+                    this.logOperation('findTasks', { detectedCustomId: taskId });
+                    try {
+                        // Try to get it as a custom ID first
+                        let resolvedListId;
+                        if (listId) {
+                            resolvedListId = listId;
+                        }
+                        else if (listName) {
+                            const listInfo = await findListIDByName(this.workspaceService, listName);
+                            if (listInfo) {
+                                resolvedListId = listInfo.id;
+                            }
+                        }
+                        const foundTask = await this.getTaskByCustomId(taskId, resolvedListId);
+                        return foundTask;
+                    }
+                    catch (error) {
+                        // If it fails as a custom ID, try as a regular ID
+                        this.logOperation('findTasks', {
+                            message: `Failed to find task with custom ID "${taskId}", falling back to regular ID`,
+                            error: error.message
+                        });
+                        return await this.getTask(taskId);
+                    }
+                }
+                // Regular task ID
+                return await this.getTask(taskId);
+            }
+            // Case 2: Explicit custom task ID lookup
+            if (customTaskId) {
+                let resolvedListId;
+                if (listId) {
+                    resolvedListId = listId;
+                }
+                else if (listName) {
+                    const listInfo = await findListIDByName(this.workspaceService, listName);
+                    if (listInfo) {
+                        resolvedListId = listInfo.id;
+                    }
+                }
+                return await this.getTaskByCustomId(customTaskId, resolvedListId);
+            }
+            // Case 3: Task name lookup (requires either list context or global lookup)
+            if (taskName) {
+                // Case 3a: Task name + list context - search in specific list
+                if (listId || listName) {
+                    let resolvedListId;
+                    if (listId) {
+                        resolvedListId = listId;
+                    }
+                    else {
+                        const listInfo = await findListIDByName(this.workspaceService, listName);
+                        if (!listInfo) {
+                            throw new Error(`List "${listName}" not found`);
+                        }
+                        resolvedListId = listInfo.id;
+                    }
+                    const foundTask = await this.findTaskByName(resolvedListId, taskName);
+                    if (!foundTask) {
+                        throw new Error(`Task "${taskName}" not found in list`);
+                    }
+                    // If includeFullDetails is true and we need context not already in the task,
+                    // get full details, otherwise return what we already have
+                    if (includeFullDetails && (!foundTask.list || !foundTask.list.name || !foundTask.status)) {
+                        return await this.getTask(foundTask.id);
+                    }
+                    return foundTask;
+                }
+                // Case 3b: Task name without list context - global lookup across workspace
+                // Get lightweight task summaries for efficient first-pass filtering
+                const response = await this.getTaskSummaries({});
+                if (!this.workspaceService) {
+                    throw new Error("Workspace service required for global task lookup");
+                }
+                // Create an index to efficiently look up list context information
+                const hierarchy = await this.workspaceService.getWorkspaceHierarchy();
+                const listContextMap = new Map();
+                // Function to recursively build list context map
+                function buildListContextMap(nodes, spaceId, spaceName, folderId, folderName) {
+                    for (const node of nodes) {
+                        if (node.type === 'space') {
+                            // Process space children
+                            if (node.children) {
+                                buildListContextMap(node.children, node.id, node.name);
+                            }
+                        }
+                        else if (node.type === 'folder') {
+                            // Process folder children
+                            if (node.children) {
+                                buildListContextMap(node.children, spaceId, spaceName, node.id, node.name);
+                            }
+                        }
+                        else if (node.type === 'list') {
+                            // Add list context to map
+                            listContextMap.set(node.id, {
+                                listId: node.id,
+                                listName: node.name,
+                                spaceId: spaceId,
+                                spaceName: spaceName,
+                                folderId,
+                                folderName
+                            });
+                        }
+                    }
+                }
+                // Build the context map
+                buildListContextMap(hierarchy.root.children);
+                // Find tasks that match the provided name
+                const initialMatches = [];
+                // Process task summaries to find initial matches
+                for (const taskSummary of response.summaries) {
+                    if (isNameMatch(taskSummary.name, taskName)) {
+                        // Get list context information
+                        const listContext = listContextMap.get(taskSummary.list.id);
+                        if (listContext) {
+                            // Store task summary and context
+                            initialMatches.push({
+                                id: taskSummary.id,
+                                task: taskSummary,
+                                listContext
+                            });
+                        }
+                    }
+                }
+                // Handle the no matches case
+                if (initialMatches.length === 0) {
+                    throw new Error(`Task "${taskName}" not found in any list across your workspace. Please check the task name and try again.`);
+                }
+                // Handle the single match case - we can return early if we don't need full details
+                if (initialMatches.length === 1 && !useSmartDisambiguation && !includeFullDetails) {
+                    const match = initialMatches[0];
+                    if (includeListContext) {
+                        return {
+                            ...match.task,
+                            list: {
+                                id: match.listContext.listId,
+                                name: match.listContext.listName
+                            },
+                            folder: match.listContext.folderId ? {
+                                id: match.listContext.folderId,
+                                name: match.listContext.folderName
+                            } : undefined,
+                            space: {
+                                id: match.listContext.spaceId,
+                                name: match.listContext.spaceName
+                            }
+                        };
+                    }
+                    return match.task;
+                }
+                // For multiple matches or when we need details, fetch full task info
+                const fullMatches = [];
+                try {
+                    // Process in sequence for better reliability
+                    for (const match of initialMatches) {
+                        const fullTask = await this.getTask(match.id);
+                        if (includeListContext) {
+                            // Enhance task with context information
+                            fullTask.list = {
+                                ...fullTask.list,
+                                name: match.listContext.listName
+                            };
+                            if (match.listContext.folderId) {
+                                fullTask.folder = {
+                                    id: match.listContext.folderId,
+                                    name: match.listContext.folderName
+                                };
+                            }
+                            fullTask.space = {
+                                id: match.listContext.spaceId,
+                                name: match.listContext.spaceName
+                            };
+                        }
+                        fullMatches.push(fullTask);
+                    }
+                    // Sort by update time for disambiguation
+                    if (fullMatches.length > 1) {
+                        fullMatches.sort((a, b) => {
+                            const aDate = parseInt(a.date_updated || '0', 10);
+                            const bDate = parseInt(b.date_updated || '0', 10);
+                            return bDate - aDate; // Most recent first
+                        });
+                    }
+                }
+                catch (error) {
+                    this.logOperation('findTasks', {
+                        error: error.message,
+                        message: "Failed to get detailed task information"
+                    });
+                    // If detailed fetch fails, use the summaries with context info
+                    // This fallback ensures we still return something useful
+                    if (allowMultipleMatches) {
+                        return initialMatches.map(match => ({
+                            ...match.task,
+                            list: {
+                                id: match.listContext.listId,
+                                name: match.listContext.listName
+                            },
+                            folder: match.listContext.folderId ? {
+                                id: match.listContext.folderId,
+                                name: match.listContext.folderName
+                            } : undefined,
+                            space: {
+                                id: match.listContext.spaceId,
+                                name: match.listContext.spaceName
+                            }
+                        }));
+                    }
+                    else {
+                        // For single result, return the first match
+                        const match = initialMatches[0];
+                        return {
+                            ...match.task,
+                            list: {
+                                id: match.listContext.listId,
+                                name: match.listContext.listName
+                            },
+                            folder: match.listContext.folderId ? {
+                                id: match.listContext.folderId,
+                                name: match.listContext.folderName
+                            } : undefined,
+                            space: {
+                                id: match.listContext.spaceId,
+                                name: match.listContext.spaceName
+                            }
+                        };
+                    }
+                }
+                // Return results based on options
+                if (fullMatches.length === 1 || useSmartDisambiguation) {
+                    return fullMatches[0]; // Return most recently updated if multiple and smart disambiguation enabled
+                }
+                else if (allowMultipleMatches) {
+                    return fullMatches; // Return all matches
+                }
+                else {
+                    // Format error message for multiple matches
+                    const matchesInfo = fullMatches.map(task => {
+                        const listName = task.list?.name || "Unknown list";
+                        const folderName = task.folder?.name;
+                        const spaceName = task.space?.name || "Unknown space";
+                        const updateTime = task.date_updated
+                            ? new Date(parseInt(task.date_updated, 10)).toLocaleString()
+                            : "Unknown date";
+                        const location = `list "${listName}"${folderName ? ` (folder: "${folderName}")` : ''} (space: "${spaceName}")`;
+                        return `- "${task.name}" in ${location} - Updated ${updateTime}`;
+                    }).join('\n');
+                    throw new Error(`Multiple tasks found with name "${taskName}":\n${matchesInfo}\n\nPlease provide list context to disambiguate or set allowMultipleMatches to true.`);
+                }
+            }
+            // No valid lookup parameters provided
+            throw new Error("At least one of taskId, customTaskId, or taskName must be provided");
+        }
+        catch (error) {
+            if (error.message?.includes('Task "') && error.message?.includes('not found')) {
+                throw error;
+            }
+            if (error.message?.includes('Multiple tasks found')) {
+                throw error;
+            }
+            // Unexpected errors
+            throw this.handleError(error, `Error finding task: ${error.message}`);
+        }
+    }
+}