/** * V3 MCP Task Tools * * MCP tools for task management operations: * - tasks/create - Create a new task * - tasks/list - List tasks with filters * - tasks/status - Get task status * - tasks/cancel - Cancel running task * - tasks/assign - Assign task to agent * - tasks/update - Update task properties * - tasks/dependencies - Manage task dependencies * - tasks/results - Get task results * * Implements ADR-005: MCP-First API Design */ import { z } from 'zod'; import { randomBytes } from 'crypto'; // Secure ID generation helper function generateSecureTaskId() { const timestamp = Date.now().toString(36); const random = randomBytes(12).toString('hex'); return `task-${timestamp}-${random}`; } // ============================================================================ // Input Schemas // ============================================================================ const createTaskSchema = z.object({ type: z.string().min(1).describe('Task type (e.g., code, review, test, analyze)'), description: z.string().min(1).describe('Task description'), priority: z.number().int().min(1).max(10).default(5) .describe('Task priority (1=highest, 10=lowest)'), dependencies: z.array(z.string()).optional() .describe('Task IDs this task depends on'), assignToAgent: z.string().optional() .describe('Specific agent ID to assign the task to'), assignToAgentType: z.string().optional() .describe('Agent type to assign the task to (will pick available agent)'), input: z.record(z.unknown()).optional() .describe('Task input data'), timeout: z.number().int().positive().optional() .describe('Task timeout in milliseconds'), metadata: z.record(z.unknown()).optional() .describe('Additional metadata'), }); const listTasksSchema = z.object({ status: z.enum(['pending', 'queued', 'assigned', 'running', 'completed', 'failed', 'cancelled', 'all']) .default('all') .describe('Filter by task status'), agentId: z.string().optional() .describe('Filter by assigned agent ID'), type: z.string().optional() .describe('Filter by task type'), priority: z.number().int().min(1).max(10).optional() .describe('Filter by priority'), limit: z.number().int().positive().max(1000).default(50) .describe('Maximum number of tasks to return'), offset: z.number().int().nonnegative().default(0) .describe('Offset for pagination'), sortBy: z.enum(['created', 'priority', 'status', 'updated']).default('created') .describe('Sort order'), sortOrder: z.enum(['asc', 'desc']).default('desc') .describe('Sort direction'), }); const taskStatusSchema = z.object({ taskId: z.string().describe('ID of the task to get status for'), includeMetrics: z.boolean().default(false) .describe('Include execution metrics'), includeHistory: z.boolean().default(false) .describe('Include status history'), }); const cancelTaskSchema = z.object({ taskId: z.string().describe('ID of the task to cancel'), reason: z.string().optional() .describe('Reason for cancellation'), force: z.boolean().default(false) .describe('Force cancellation even if task is running'), }); const assignTaskSchema = z.object({ taskId: z.string().describe('ID of the task to assign'), agentId: z.string().describe('ID of the agent to assign to'), reassign: z.boolean().default(false) .describe('Allow reassignment if task is already assigned'), }); const updateTaskSchema = z.object({ taskId: z.string().describe('ID of the task to update'), priority: z.number().int().min(1).max(10).optional() .describe('New priority'), description: z.string().optional() .describe('New description'), timeout: z.number().int().positive().optional() .describe('New timeout'), metadata: z.record(z.unknown()).optional() .describe('Metadata to merge'), }); const taskDependenciesSchema = z.object({ taskId: z.string().describe('ID of the task'), action: z.enum(['add', 'remove', 'list', 'clear']) .describe('Action to perform on dependencies'), dependencies: z.array(z.string()).optional() .describe('Dependencies to add or remove'), }); const taskResultsSchema = z.object({ taskId: z.string().describe('ID of the task to get results for'), format: z.enum(['summary', 'detailed', 'raw']).default('summary') .describe('Result format'), includeArtifacts: z.boolean().default(true) .describe('Include generated artifacts'), }); // ============================================================================ // In-memory task store (for simple implementation) // ============================================================================ const taskStore = new Map(); const taskResults = new Map(); // ============================================================================ // Tool Handlers // ============================================================================ /** * Create a new task */ async function handleCreateTask(input, context) { const taskId = generateSecureTaskId(); const createdAt = new Date().toISOString(); const task = { id: taskId, type: input.type, description: input.description, status: 'pending', priority: input.priority, dependencies: input.dependencies || [], assignedTo: input.assignToAgent, createdAt, timeout: input.timeout, input: input.input, metadata: input.metadata, }; // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; // Submit task to orchestrator const result = await orchestrator.submitTask({ id: taskId, type: input.type, description: input.description, priority: input.priority, dependencies: input.dependencies, assignedAgent: input.assignToAgent, input: input.input, timeout: input.timeout, metadata: input.metadata, }); return { taskId: result.id || taskId, status: result.status || 'queued', createdAt, queuePosition: result.queuePosition, }; } catch (error) { console.error('Failed to create task via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation if (task.assignedTo) { task.status = 'assigned'; } taskStore.set(taskId, task); return { taskId, status: task.status, createdAt, queuePosition: taskStore.size, }; } /** * List tasks with filters */ async function handleListTasks(input, context) { // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.listTasks({ status: input.status === 'all' ? undefined : input.status, agentId: input.agentId, type: input.type, priority: input.priority, limit: input.limit, offset: input.offset, sortBy: input.sortBy, sortOrder: input.sortOrder, }); return { tasks: result.tasks.map((t) => ({ id: t.id, type: t.type, description: t.description, status: t.status, priority: t.priority, dependencies: t.dependencies || [], assignedTo: t.assignedAgent, createdAt: t.createdAt, updatedAt: t.updatedAt, startedAt: t.startedAt, completedAt: t.completedAt, timeout: t.timeout, input: t.input, metadata: t.metadata, })), total: result.total, limit: input.limit, offset: input.offset, }; } catch (error) { console.error('Failed to list tasks via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation let tasks = Array.from(taskStore.values()); // Apply filters if (input.status !== 'all') { tasks = tasks.filter(t => t.status === input.status); } if (input.agentId) { tasks = tasks.filter(t => t.assignedTo === input.agentId); } if (input.type) { tasks = tasks.filter(t => t.type === input.type); } if (input.priority !== undefined) { tasks = tasks.filter(t => t.priority === input.priority); } // Apply sorting tasks.sort((a, b) => { let aVal; let bVal; switch (input.sortBy) { case 'created': aVal = new Date(a.createdAt).getTime(); bVal = new Date(b.createdAt).getTime(); break; case 'priority': aVal = a.priority; bVal = b.priority; break; case 'status': aVal = a.status; bVal = b.status; break; case 'updated': aVal = a.updatedAt ? new Date(a.updatedAt).getTime() : new Date(a.createdAt).getTime(); bVal = b.updatedAt ? new Date(b.updatedAt).getTime() : new Date(b.createdAt).getTime(); break; default: aVal = 0; bVal = 0; } if (input.sortOrder === 'asc') { return aVal < bVal ? -1 : aVal > bVal ? 1 : 0; } else { return aVal > bVal ? -1 : aVal < bVal ? 1 : 0; } }); const total = tasks.length; const paginated = tasks.slice(input.offset, input.offset + input.limit); return { tasks: paginated, total, limit: input.limit, offset: input.offset, }; } /** * Get task status */ async function handleTaskStatus(input, context) { // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.getTaskStatus(input.taskId, { includeMetrics: input.includeMetrics, includeHistory: input.includeHistory, }); const task = { id: result.id, type: result.type, description: result.description, status: result.status, priority: result.priority, dependencies: result.dependencies || [], assignedTo: result.assignedAgent, createdAt: result.createdAt, updatedAt: result.updatedAt, startedAt: result.startedAt, completedAt: result.completedAt, timeout: result.timeout, input: result.input, metadata: result.metadata, }; if (input.includeMetrics && result.metrics) { task.metrics = result.metrics; } if (input.includeHistory && result.history) { task.history = result.history; } return task; } catch (error) { console.error('Failed to get task status via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } const result = { ...task }; if (input.includeMetrics) { result.metrics = { executionTime: 0, retryCount: 0, waitTime: 0, }; } if (input.includeHistory) { result.history = [ { timestamp: task.createdAt, status: 'pending', message: 'Task created', }, ]; if (task.status !== 'pending') { result.history.push({ timestamp: task.updatedAt || task.createdAt, status: task.status, message: `Status changed to ${task.status}`, }); } } return result; } /** * Cancel a task */ async function handleCancelTask(input, context) { const cancelledAt = new Date().toISOString(); // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.cancelTask(input.taskId, { reason: input.reason, force: input.force, }); return { taskId: input.taskId, cancelled: result.cancelled, cancelledAt, previousStatus: result.previousStatus, reason: input.reason, }; } catch (error) { console.error('Failed to cancel task via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } const previousStatus = task.status; // Check if task can be cancelled if (task.status === 'completed' || task.status === 'cancelled') { return { taskId: input.taskId, cancelled: false, cancelledAt, previousStatus, reason: `Task is already ${task.status}`, }; } if (task.status === 'running' && !input.force) { return { taskId: input.taskId, cancelled: false, cancelledAt, previousStatus, reason: 'Task is running. Use force=true to cancel.', }; } // Cancel the task task.status = 'cancelled'; task.updatedAt = cancelledAt; task.completedAt = cancelledAt; if (input.reason) { task.metadata = { ...task.metadata, cancelReason: input.reason }; } return { taskId: input.taskId, cancelled: true, cancelledAt, previousStatus, reason: input.reason, }; } /** * Assign a task to an agent */ async function handleAssignTask(input, context) { const assignedAt = new Date().toISOString(); // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.assignTask(input.taskId, input.agentId, { reassign: input.reassign, }); return { taskId: input.taskId, agentId: input.agentId, assigned: result.assigned, assignedAt, previousAgent: result.previousAgent, }; } catch (error) { console.error('Failed to assign task via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } const previousAgent = task.assignedTo; // Check if task can be assigned if (task.assignedTo && !input.reassign) { return { taskId: input.taskId, agentId: input.agentId, assigned: false, assignedAt, previousAgent, }; } if (task.status === 'completed' || task.status === 'cancelled' || task.status === 'failed') { throw new Error(`Cannot assign task with status: ${task.status}`); } // Assign the task task.assignedTo = input.agentId; task.status = 'assigned'; task.updatedAt = assignedAt; return { taskId: input.taskId, agentId: input.agentId, assigned: true, assignedAt, previousAgent, }; } /** * Update task properties */ async function handleUpdateTask(input, context) { const updatedAt = new Date().toISOString(); const changes = {}; // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.updateTask(input.taskId, { priority: input.priority, description: input.description, timeout: input.timeout, metadata: input.metadata, }); return { taskId: input.taskId, updated: result.updated, updatedAt, changes: result.changes || {}, }; } catch (error) { console.error('Failed to update task via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } // Check if task can be updated if (task.status === 'completed' || task.status === 'cancelled') { throw new Error(`Cannot update task with status: ${task.status}`); } // Apply updates if (input.priority !== undefined && input.priority !== task.priority) { changes.priority = { from: task.priority, to: input.priority }; task.priority = input.priority; } if (input.description !== undefined && input.description !== task.description) { changes.description = { from: task.description, to: input.description }; task.description = input.description; } if (input.timeout !== undefined && input.timeout !== task.timeout) { changes.timeout = { from: task.timeout, to: input.timeout }; task.timeout = input.timeout; } if (input.metadata) { changes.metadata = { from: task.metadata, to: { ...task.metadata, ...input.metadata } }; task.metadata = { ...task.metadata, ...input.metadata }; } task.updatedAt = updatedAt; return { taskId: input.taskId, updated: Object.keys(changes).length > 0, updatedAt, changes, }; } /** * Manage task dependencies */ async function handleTaskDependencies(input, context) { const updatedAt = new Date().toISOString(); // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; let result; switch (input.action) { case 'add': result = await orchestrator.addTaskDependencies(input.taskId, input.dependencies || []); break; case 'remove': result = await orchestrator.removeTaskDependencies(input.taskId, input.dependencies || []); break; case 'list': result = await orchestrator.getTaskDependencies(input.taskId); break; case 'clear': result = await orchestrator.clearTaskDependencies(input.taskId); break; } return { taskId: input.taskId, action: input.action, dependencies: result?.dependencies || [], updatedAt: input.action !== 'list' ? updatedAt : undefined, }; } catch (error) { console.error('Failed to manage task dependencies via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } switch (input.action) { case 'add': if (input.dependencies) { task.dependencies = Array.from(new Set([...task.dependencies, ...input.dependencies])); task.updatedAt = updatedAt; } break; case 'remove': if (input.dependencies) { task.dependencies = task.dependencies.filter(d => !input.dependencies.includes(d)); task.updatedAt = updatedAt; } break; case 'list': // No changes needed break; case 'clear': task.dependencies = []; task.updatedAt = updatedAt; break; } return { taskId: input.taskId, action: input.action, dependencies: task.dependencies, updatedAt: input.action !== 'list' ? updatedAt : undefined, }; } /** * Get task results */ async function handleTaskResults(input, context) { // Try to use orchestrator if available if (context?.orchestrator) { try { const orchestrator = context.orchestrator; const result = await orchestrator.getTaskResults(input.taskId, { format: input.format, includeArtifacts: input.includeArtifacts, }); return { taskId: input.taskId, status: result.status, success: result.success, output: result.output, error: result.error, artifacts: input.includeArtifacts ? result.artifacts : undefined, executionTime: result.executionTime, completedAt: result.completedAt, }; } catch (error) { console.error('Failed to get task results via orchestrator:', error); // Fall through to simple implementation } } // Simple implementation const task = taskStore.get(input.taskId); if (!task) { throw new Error(`Task not found: ${input.taskId}`); } // Check if task has results const result = taskResults.get(input.taskId); if (result) { return { ...result, artifacts: input.includeArtifacts ? result.artifacts : undefined, }; } // Task exists but no results yet return { taskId: input.taskId, status: task.status, success: task.status === 'completed', output: undefined, error: task.status === 'failed' ? { code: 'TASK_FAILED', message: 'Task failed to complete', } : undefined, completedAt: task.completedAt, }; } // ============================================================================ // Tool Definitions // ============================================================================ /** * tasks/create tool */ export const createTaskTool = { name: 'tasks/create', description: 'Create a new task for execution with specified type, priority, and configuration', inputSchema: { type: 'object', properties: { type: { type: 'string', description: 'Task type (e.g., code, review, test, analyze)', }, description: { type: 'string', description: 'Task description', }, priority: { type: 'number', description: 'Task priority (1=highest, 10=lowest)', minimum: 1, maximum: 10, default: 5, }, dependencies: { type: 'array', items: { type: 'string' }, description: 'Task IDs this task depends on', }, assignToAgent: { type: 'string', description: 'Specific agent ID to assign the task to', }, assignToAgentType: { type: 'string', description: 'Agent type to assign the task to', }, input: { type: 'object', description: 'Task input data', additionalProperties: true, }, timeout: { type: 'number', description: 'Task timeout in milliseconds', minimum: 1, }, metadata: { type: 'object', description: 'Additional metadata', additionalProperties: true, }, }, required: ['type', 'description'], }, handler: async (input, context) => { const validated = createTaskSchema.parse(input); return handleCreateTask(validated, context); }, category: 'task', tags: ['task', 'create', 'orchestration'], version: '1.0.0', }; /** * tasks/list tool */ export const listTasksTool = { name: 'tasks/list', description: 'List tasks with optional filtering, sorting, and pagination', inputSchema: { type: 'object', properties: { status: { type: 'string', enum: ['pending', 'queued', 'assigned', 'running', 'completed', 'failed', 'cancelled', 'all'], description: 'Filter by task status', default: 'all', }, agentId: { type: 'string', description: 'Filter by assigned agent ID', }, type: { type: 'string', description: 'Filter by task type', }, priority: { type: 'number', description: 'Filter by priority', minimum: 1, maximum: 10, }, limit: { type: 'number', description: 'Maximum number of tasks to return', minimum: 1, maximum: 1000, default: 50, }, offset: { type: 'number', description: 'Offset for pagination', minimum: 0, default: 0, }, sortBy: { type: 'string', enum: ['created', 'priority', 'status', 'updated'], description: 'Sort order', default: 'created', }, sortOrder: { type: 'string', enum: ['asc', 'desc'], description: 'Sort direction', default: 'desc', }, }, }, handler: async (input, context) => { const validated = listTasksSchema.parse(input); return handleListTasks(validated, context); }, category: 'task', tags: ['task', 'list', 'query'], version: '1.0.0', cacheable: true, cacheTTL: 2000, }; /** * tasks/status tool */ export const taskStatusTool = { name: 'tasks/status', description: 'Get detailed status of a specific task including optional metrics and history', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task to get status for', }, includeMetrics: { type: 'boolean', description: 'Include execution metrics', default: false, }, includeHistory: { type: 'boolean', description: 'Include status history', default: false, }, }, required: ['taskId'], }, handler: async (input, context) => { const validated = taskStatusSchema.parse(input); return handleTaskStatus(validated, context); }, category: 'task', tags: ['task', 'status', 'monitoring'], version: '1.0.0', cacheable: true, cacheTTL: 1000, }; /** * tasks/cancel tool */ export const cancelTaskTool = { name: 'tasks/cancel', description: 'Cancel a pending or running task', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task to cancel', }, reason: { type: 'string', description: 'Reason for cancellation', }, force: { type: 'boolean', description: 'Force cancellation even if task is running', default: false, }, }, required: ['taskId'], }, handler: async (input, context) => { const validated = cancelTaskSchema.parse(input); return handleCancelTask(validated, context); }, category: 'task', tags: ['task', 'cancel', 'lifecycle'], version: '1.0.0', }; /** * tasks/assign tool */ export const assignTaskTool = { name: 'tasks/assign', description: 'Assign a task to a specific agent', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task to assign', }, agentId: { type: 'string', description: 'ID of the agent to assign to', }, reassign: { type: 'boolean', description: 'Allow reassignment if task is already assigned', default: false, }, }, required: ['taskId', 'agentId'], }, handler: async (input, context) => { const validated = assignTaskSchema.parse(input); return handleAssignTask(validated, context); }, category: 'task', tags: ['task', 'assign', 'agent'], version: '1.0.0', }; /** * tasks/update tool */ export const updateTaskTool = { name: 'tasks/update', description: 'Update task properties like priority, description, timeout, or metadata', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task to update', }, priority: { type: 'number', description: 'New priority', minimum: 1, maximum: 10, }, description: { type: 'string', description: 'New description', }, timeout: { type: 'number', description: 'New timeout in milliseconds', minimum: 1, }, metadata: { type: 'object', description: 'Metadata to merge', additionalProperties: true, }, }, required: ['taskId'], }, handler: async (input, context) => { const validated = updateTaskSchema.parse(input); return handleUpdateTask(validated, context); }, category: 'task', tags: ['task', 'update', 'modify'], version: '1.0.0', }; /** * tasks/dependencies tool */ export const taskDependenciesTool = { name: 'tasks/dependencies', description: 'Manage task dependencies - add, remove, list, or clear', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task', }, action: { type: 'string', enum: ['add', 'remove', 'list', 'clear'], description: 'Action to perform on dependencies', }, dependencies: { type: 'array', items: { type: 'string' }, description: 'Dependencies to add or remove', }, }, required: ['taskId', 'action'], }, handler: async (input, context) => { const validated = taskDependenciesSchema.parse(input); return handleTaskDependencies(validated, context); }, category: 'task', tags: ['task', 'dependencies', 'dag'], version: '1.0.0', }; /** * tasks/results tool */ export const taskResultsTool = { name: 'tasks/results', description: 'Get results from a completed task including output, errors, and artifacts', inputSchema: { type: 'object', properties: { taskId: { type: 'string', description: 'ID of the task to get results for', }, format: { type: 'string', enum: ['summary', 'detailed', 'raw'], description: 'Result format', default: 'summary', }, includeArtifacts: { type: 'boolean', description: 'Include generated artifacts', default: true, }, }, required: ['taskId'], }, handler: async (input, context) => { const validated = taskResultsSchema.parse(input); return handleTaskResults(validated, context); }, category: 'task', tags: ['task', 'results', 'output'], version: '1.0.0', cacheable: true, cacheTTL: 5000, }; // ============================================================================ // Exports // ============================================================================ export const taskTools = [ createTaskTool, listTasksTool, taskStatusTool, cancelTaskTool, assignTaskTool, updateTaskTool, taskDependenciesTool, taskResultsTool, ]; export default taskTools; //# sourceMappingURL=task-tools.js.map