agenthub-multiagent-mcp 1.1.5 → 1.4.0

package/src/tools/index.ts

@@ -2,49 +2,92 @@
  * MCP tool definitions and handlers
  */
 
-import { ApiClient, Message } from "../client.js";
+import { ApiClient, Message, TicketTask, TicketTaskContext, CheckpointResponse } from "../client.js";
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import * as state from "../state.js";
+import open from "open";
+
+export interface PushedItems {
+  tasks: PendingTask[];
+  messages: Message[];
+}
 
 export interface ToolContext {
   getCurrentAgentId: () => string;
   setCurrentAgentId: (id: string) => void;
   stopHeartbeat: () => void;
   getWorkingDir: () => string;
+  getPushedItems: () => PushedItems;
+}
+
+interface PendingTask {
+  id: string;
+  assigned_by: string;
+  assigned_by_name?: string;
+  task: string;
+  priority: string;
+  created_at: string;
 }
 
 interface UrgentAction {
   required: true;
   instruction: string;
-  message: Message;
+  message?: Message;
+  task?: PendingTask;
 }
 
 interface WrappedResponse {
   result: unknown;
   pending_messages: Message[];
-  pending_count: number;
-  has_more: boolean;
+  pending_messages_count: number;
+  pending_tasks: PendingTask[];
+  pending_tasks_count: number;
   urgent_action: UrgentAction | null;
 }
 
 /**
- * Wraps a tool response with pending messages
- * This enables automatic message delivery without extra API calls
+ * Wraps a tool response with pending messages and tasks
+ * This enables automatic delivery without extra API calls
+ * Includes items pushed via WebSocket
  */
-async function wrapWithMessages(
+async function wrapWithPendingItems(
   client: ApiClient,
   agentId: string | null,
-  result: unknown
+  result: unknown,
+  context?: ToolContext
 ): Promise<WrappedResponse | unknown> {
   // If not registered, return raw result
   if (!agentId) return result;
 
   try {
-    // Fetch unread messages
-    const inbox = await client.getInbox(agentId, true, 10);
-    const messages = inbox.messages || [];
+    // Get items pushed via WebSocket (if connected)
+    const pushedItems = context?.getPushedItems() || { tasks: [], messages: [] };
+
+    // Fetch unread messages and pending tasks in parallel
+    const [inbox, tasksResponse] = await Promise.all([
+      client.getInbox(agentId, true, 10),
+      client.getPendingTasks(agentId),
+    ]);
+
+    // Merge pushed items with fetched items (deduplicating by ID)
+    const fetchedMessages = inbox.messages || [];
+    const fetchedTasks = (tasksResponse.tasks || []) as PendingTask[];
+
+    // Deduplicate messages
+    const messageIds = new Set(fetchedMessages.map((m) => m.id));
+    const messages = [
+      ...fetchedMessages,
+      ...pushedItems.messages.filter((m) => !messageIds.has(m.id)),
+    ];
 
-    // Sort: urgent first, then by created_at
+    // Deduplicate tasks
+    const taskIds = new Set(fetchedTasks.map((t) => t.id));
+    const tasks = [
+      ...fetchedTasks,
+      ...pushedItems.tasks.filter((t) => !taskIds.has(t.id)),
+    ];
+
+    // Sort messages: urgent first, then by created_at
     messages.sort((a, b) => {
       const aUrgent = isUrgentMessage(a);
       const bUrgent = isUrgentMessage(b);
@@ -53,28 +96,40 @@ async function wrapWithMessages(
       return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
     });
 
-    // Find urgent message for action
-    const urgentMsg = messages.find(isUrgentMessage);
-
+    // Determine urgent action - tasks take priority over messages
     let urgentAction: UrgentAction | null = null;
-    if (urgentMsg) {
+
+    // Check for pending tasks first (they're actionable)
+    if (tasks.length > 0) {
+      const highPriorityTask = tasks.find((t) => t.priority === "high") || tasks[0];
       urgentAction = {
         required: true,
-        instruction: buildUrgentInstruction(urgentMsg),
-        message: urgentMsg,
+        instruction: buildTaskInstruction(highPriorityTask),
+        task: highPriorityTask,
       };
+    } else {
+      // Check for urgent messages
+      const urgentMsg = messages.find(isUrgentMessage);
+      if (urgentMsg) {
+        urgentAction = {
+          required: true,
+          instruction: buildUrgentInstruction(urgentMsg),
+          message: urgentMsg,
+        };
+      }
     }
 
     return {
       result,
       pending_messages: messages,
-      pending_count: inbox.total,
-      has_more: inbox.total > messages.length,
+      pending_messages_count: messages.length,
+      pending_tasks: tasks,
+      pending_tasks_count: tasks.length,
       urgent_action: urgentAction,
     };
   } catch (error) {
-    // Don't break tool call if message fetch fails
-    console.warn("Failed to fetch messages for wrapping:", error);
+    // Don't break tool call if fetch fails
+    console.warn("Failed to fetch pending items for wrapping:", error);
     return result;
   }
 }
@@ -102,6 +157,18 @@ Details: ${msg.body}
 Spawn a subagent with Task tool to research and respond to this query. Use send_message to reply when done.`;
 }
 
+/**
+ * Build instruction text for pending tasks
+ */
+function buildTaskInstruction(task: PendingTask): string {
+  const assignerName = task.assigned_by_name || task.assigned_by;
+  return `ACTION REQUIRED: You have a task assigned by ${assignerName}.
+
+Task: ${task.task}
+
+Use accept_task with task_id="${task.id}" to accept and start working, or decline_task to decline with a reason.`;
+}
+
 export function registerTools(): Tool[] {
   return [
     // Registration tools
@@ -141,6 +208,10 @@ export function registerTools(): Tool[] {
             type: "string",
             description: "Project name (optional)",
           },
+          task_id: {
+            type: "string",
+            description: "Optional: ID of a ticket system task to link this work to",
+          },
         },
         required: ["task"],
       },
@@ -439,6 +510,230 @@ export function registerTools(): Tool[] {
         required: ["task_id", "reason"],
       },
     },
+
+    // Ticket system tools (for project management integration)
+    {
+      name: "get_available_tasks",
+      description: "Get tasks from the ticket system that are available for you to claim and work on",
+      inputSchema: {
+        type: "object",
+        properties: {
+          status: {
+            type: "string",
+            description: "Filter by status (default: todo)",
+            enum: ["backlog", "todo", "in_progress"],
+          },
+          project_id: {
+            type: "string",
+            description: "Filter by project ID (optional)",
+          },
+          priority: {
+            type: "string",
+            description: "Filter by priority (optional)",
+            enum: ["lowest", "low", "medium", "high", "highest"],
+          },
+          required_type: {
+            type: "string",
+            description: "Filter by required skill type - matches your agent type",
+            enum: ["frontend", "backend", "android", "ios", "ai", "design-specs"],
+          },
+          match_my_type: {
+            type: "boolean",
+            description: "If true, only show tasks matching your registered agent type",
+          },
+        },
+      },
+    },
+    {
+      name: "get_task_context",
+      description: "Get full context for a ticket task including its parent story and epic",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "ID of the task to get context for",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+    {
+      name: "claim_ticket_task",
+      description: "Claim a ticket task from the project board to work on",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "ID of the task to claim",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+    {
+      name: "reach_checkpoint",
+      description: "Signal that you've reached a checkpoint and request human review before continuing",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: {
+            type: "string",
+            description: "ID of the task you're working on",
+          },
+          description: {
+            type: "string",
+            description: "Description of what you've accomplished and what you're waiting for review on",
+          },
+        },
+        required: ["task_id", "description"],
+      },
+    },
+
+    // Ticket creation tools
+    {
+      name: "create_epic",
+      description: "Create an epic (large body of work) in a project",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: {
+            type: "string",
+            description: "Project ID to create epic in",
+          },
+          title: {
+            type: "string",
+            description: "Epic title",
+          },
+          description: {
+            type: "string",
+            description: "Epic description (supports markdown)",
+          },
+          source_file: {
+            type: "string",
+            description: "Optional: path to OpenSpec file this came from",
+          },
+        },
+        required: ["project_id", "title"],
+      },
+    },
+    {
+      name: "create_story",
+      description: "Create a story under an epic",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: {
+            type: "string",
+            description: "Project ID",
+          },
+          epic_id: {
+            type: "string",
+            description: "Epic ID to add story to",
+          },
+          title: {
+            type: "string",
+            description: "Story title",
+          },
+          description: {
+            type: "string",
+            description: "Story description",
+          },
+          required_type: {
+            type: "string",
+            enum: ["frontend", "backend", "android", "ios", "ai", "design-specs"],
+            description: "Required skill type for this story",
+          },
+          labels: {
+            type: "array",
+            items: { type: "string" },
+            description: "Additional labels",
+          },
+        },
+        required: ["project_id", "title"],
+      },
+    },
+    {
+      name: "create_task",
+      description: "Create a task under a story",
+      inputSchema: {
+        type: "object",
+        properties: {
+          project_id: {
+            type: "string",
+            description: "Project ID",
+          },
+          story_id: {
+            type: "string",
+            description: "Story ID to add task to",
+          },
+          title: {
+            type: "string",
+            description: "Task title",
+          },
+          description: {
+            type: "string",
+            description: "Task description",
+          },
+          required_type: {
+            type: "string",
+            enum: ["frontend", "backend", "android", "ios", "ai", "design-specs"],
+            description: "Required skill type",
+          },
+        },
+        required: ["project_id", "title"],
+      },
+    },
+    {
+      name: "upload_attachment",
+      description: "Upload a file (screenshot, log, etc.) as proof of work to a ticket",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticket_id: {
+            type: "string",
+            description: "Ticket ID to attach file to",
+          },
+          ticket_type: {
+            type: "string",
+            enum: ["epic", "story", "task"],
+            description: "Type of ticket",
+          },
+          ticket_key: {
+            type: "string",
+            description: "Ticket key (e.g., PROJ-T42)",
+          },
+          file_path: {
+            type: "string",
+            description: "Local path to file to upload",
+          },
+          description: {
+            type: "string",
+            description: "Optional description of the file",
+          },
+        },
+        required: ["ticket_id", "ticket_type", "ticket_key", "file_path"],
+      },
+    },
+    {
+      name: "add_comment",
+      description: "Add a comment to any ticket (epic, story, task)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ticket_id: {
+            type: "string",
+            description: "Ticket ID to comment on",
+          },
+          body: {
+            type: "string",
+            description: "Comment body (supports markdown)",
+          },
+        },
+        required: ["ticket_id", "body"],
+      },
+    },
   ];
 }
 
@@ -503,35 +798,69 @@ export async function handleToolCall(
         }
       }
 
-      // Fresh registration
-      // Auto-detect model from environment or use provided value
-      const model = args.model as string ||
-                    process.env.CLAUDE_MODEL ||
-                    "claude-opus-4-5-20251101";
-
-      const result = await client.registerAgent(
+      // Fresh registration - use browser-based flow
+      // Step 1: Initialize registration session
+      const initResult = await client.initRegistration(
         requestedId,
-        args.name as string | undefined,
-        owner,
-        workingDir,
-        model
+        args.name as string | undefined
       );
 
-      context.setCurrentAgentId(requestedId);
+      // Step 2: Open browser to dashboard
+      const dashboardUrl = client.getBaseUrl().replace('/api', '') + initResult.dashboard_url;
+      console.error(`Opening browser for agent registration: ${dashboardUrl}`);
+      await open(dashboardUrl);
+
+      // Step 3: Poll for completion (max 10 minutes)
+      const pollInterval = 3000; // 3 seconds
+      const maxPolls = 200; // 10 minutes
+      let pollCount = 0;
+      let registrationResult: Awaited<ReturnType<typeof client.pollRegistrationCallback>> | null = null;
+
+      console.error('Waiting for browser registration to complete...');
+      
+      while (pollCount < maxPolls) {
+        await new Promise(resolve => setTimeout(resolve, pollInterval));
+        pollCount++;
+        
+        try {
+          const pollResult = await client.pollRegistrationCallback(initResult.session_token);
+          
+          if (pollResult.status === 'completed') {
+            registrationResult = pollResult;
+            break;
+          } else if (pollResult.status === 'expired') {
+            throw new Error('Registration session expired. Please try again.');
+          }
+          // status === 'pending' - continue polling
+        } catch (error) {
+          // Non-fatal errors during polling - continue
+          console.warn('Poll error:', error);
+        }
+      }
+
+      if (!registrationResult || registrationResult.status !== 'completed') {
+        throw new Error('Registration timed out. Please try again.');
+      }
+
+      const agentId = registrationResult.agent_id!;
+      context.setCurrentAgentId(agentId);
 
-      // Save state for future reconnection (including name)
+      // Save state for future reconnection
       state.saveState(workingDir, {
-        agent_id: requestedId,
-        name: result.name,
+        agent_id: agentId,
+        name: registrationResult.agent_name || agentId,
         owner,
-        token: result.token,
-        registered_at: result.registered_at,
+        token: registrationResult.connect_token!,
+        agent_type: registrationResult.agent_type,
+        registered_at: new Date().toISOString(),
       });
 
       return {
-        ...result,
-        mode: "registered",
-        message: `Registered as ${result.name || requestedId}. You have ${result.pending_tasks_count} pending tasks and ${result.unread_messages_count} unread messages.`,
+        agent_id: agentId,
+        name: registrationResult.agent_name,
+        agent_type: registrationResult.agent_type,
+        mode: 'registered',
+        message: `Successfully registered as ${registrationResult.agent_name || agentId}. You can now use other AgentHub tools.`,
       };
     }
 
@@ -540,15 +869,16 @@ export async function handleToolCall(
       const result = await client.startWork(
         agentId,
         args.task as string,
-        args.project as string | undefined
+        args.project as string | undefined,
+        args.task_id as string | undefined
       );
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "agent_set_status": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.heartbeat(agentId, args.status as "online" | "busy");
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "agent_disconnect": {
@@ -569,7 +899,7 @@ export async function handleToolCall(
         body: args.body as string,
         priority: args.priority as string | undefined,
       });
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "send_to_channel": {
@@ -581,7 +911,7 @@ export async function handleToolCall(
         subject: args.subject as string,
         body: args.body as string,
       });
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "broadcast": {
@@ -593,7 +923,7 @@ export async function handleToolCall(
         subject: args.subject as string,
         body: args.body as string,
       });
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "check_inbox": {
@@ -604,41 +934,41 @@ export async function handleToolCall(
 
     case "mark_read": {
       const result = await client.markRead(args.message_id as string);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "reply": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.reply(args.message_id as string, agentId, args.body as string);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     // Discovery
     case "list_agents": {
       const result = await client.listAgents(args.status as string | undefined);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "get_agent": {
       const result = await client.getAgent(args.id as string);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "list_channels": {
       const result = await client.listChannels();
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "join_channel": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.joinChannel(args.channel as string, agentId);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "leave_channel": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.leaveChannel(args.channel as string, agentId);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     // Task completion
@@ -651,25 +981,141 @@ export async function handleToolCall(
         time_spent: args.time_spent as string | undefined,
         next_steps: args.next_steps as string | undefined,
       });
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "get_pending_tasks": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.getPendingTasks(agentId);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "accept_task": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.acceptTask(agentId, args.task_id as string);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
     }
 
     case "decline_task": {
       if (!agentId) throw new Error("Not registered. Call agent_register first.");
       const result = await client.declineTask(agentId, args.task_id as string, args.reason as string);
-      return wrapWithMessages(client, agentId, result);
+      return wrapWithPendingItems(client, agentId, result, context);
+    }
+
+    // Ticket system tools
+    case "get_available_tasks": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+
+      let requiredType = args.required_type as string | undefined;
+
+      // If match_my_type is true, get agent's type from state
+      if (args.match_my_type === true) {
+        const workingDir = context.getWorkingDir();
+        const agentState = state.loadState(workingDir);
+        // Use stored agent_type if available, otherwise keep the explicit required_type
+        requiredType = requiredType || agentState?.agent_type;
+      }
+
+      const result = await client.getAvailableTasks({
+        status: args.status as string | undefined,
+        project_id: args.project_id as string | undefined,
+        priority: args.priority as string | undefined,
+        required_type: requiredType,
+      });
+      return wrapWithPendingItems(client, agentId, result, context);
+    }
+
+    case "get_task_context": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+      const result = await client.getTicketTask(args.task_id as string);
+      return wrapWithPendingItems(client, agentId, result, context);
+    }
+
+    case "claim_ticket_task": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+      const result = await client.claimTicketTask(args.task_id as string, agentId);
+      return wrapWithPendingItems(client, agentId, result, context);
+    }
+
+    case "reach_checkpoint": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+      const result = await client.createCheckpoint(
+        args.task_id as string,
+        agentId,
+        args.description as string
+      );
+      return wrapWithPendingItems(client, agentId, result, context);
+    }
+
+    // Ticket creation tools
+    case "create_epic": {
+      const result = await client.createEpic({
+        project_id: args.project_id as string,
+        title: args.title as string,
+        description: args.description as string | undefined,
+        source_file: args.source_file as string | undefined,
+      });
+      return {
+        ...result,
+        message: `Created epic ${result.key}: ${args.title}`,
+      };
+    }
+
+    case "create_story": {
+      const result = await client.createStory({
+        project_id: args.project_id as string,
+        epic_id: args.epic_id as string | undefined,
+        title: args.title as string,
+        description: args.description as string | undefined,
+        required_type: args.required_type as string | undefined,
+        labels: args.labels as string[] | undefined,
+      });
+      return {
+        ...result,
+        message: `Created story ${result.key}: ${args.title}`,
+      };
+    }
+
+    case "create_task": {
+      const result = await client.createTask({
+        project_id: args.project_id as string,
+        story_id: args.story_id as string | undefined,
+        title: args.title as string,
+        description: args.description as string | undefined,
+        required_type: args.required_type as string | undefined,
+      });
+      return {
+        ...result,
+        message: `Created task ${result.key}: ${args.title}`,
+      };
+    }
+
+    case "upload_attachment": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+      const result = await client.uploadAttachment({
+        ticket_id: args.ticket_id as string,
+        ticket_type: args.ticket_type as string,
+        ticket_key: args.ticket_key as string,
+        file_path: args.file_path as string,
+        description: args.description as string | undefined,
+        agent_id: agentId,
+      });
+      return {
+        ...result,
+        message: `Uploaded ${result.filename} to ${args.ticket_key}`,
+      };
+    }
+
+    case "add_comment": {
+      if (!agentId) throw new Error("Not registered. Call agent_register first.");
+      const result = await client.addComment({
+        ticket_id: args.ticket_id as string,
+        body: args.body as string,
+      });
+      return {
+        ...result,
+        message: `Added comment to ticket`,
+      };
     }
 
     default: