agenthub-multiagent-mcp 1.1.4 → 1.3.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 || [];
-
-    // Sort: urgent first, then by created_at
+    // 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)),
+    ];
+
+    // 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,77 @@ 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"],
+          },
+        },
+      },
+    },
+    {
+      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"],
+      },
+    },
   ];
 }
 
@@ -468,18 +610,23 @@ export async function handleToolCall(
         } else {
           // Try to reconnect
           try {
+            // Use provided name, or fall back to stored name
+            const reconnectName = (args.name as string) || existingState.name;
+
             const reconnectResult = await client.reconnectAgent(
               existingState.agent_id,
               existingState.token,
               owner,
-              args.model as string // Pass the requested model to update it
+              args.model as string,
+              reconnectName
             );
 
             context.setCurrentAgentId(existingState.agent_id);
 
-            // Update state with any new info
+            // Update state with returned name from server
             state.saveState(workingDir, {
               ...existingState,
+              name: reconnectResult.name,
               last_task: undefined, // Cleared on reconnect
             });
 
@@ -487,8 +634,8 @@ export async function handleToolCall(
               ...reconnectResult,
               mode: "reconnected",
               message: reconnectResult.was_offline
-                ? `Reconnected after timeout. You have ${reconnectResult.pending_tasks_count} pending tasks and ${reconnectResult.unread_messages_count} unread messages.`
-                : `Reconnected. You have ${reconnectResult.pending_tasks_count} pending tasks and ${reconnectResult.unread_messages_count} unread messages.`,
+                ? `Reconnected as ${reconnectResult.name || existingState.agent_id}. You have ${reconnectResult.pending_tasks_count} pending tasks and ${reconnectResult.unread_messages_count} unread messages.`
+                : `Reconnected as ${reconnectResult.name || existingState.agent_id}. You have ${reconnectResult.pending_tasks_count} pending tasks and ${reconnectResult.unread_messages_count} unread messages.`,
             };
           } catch (error) {
             // Reconnection failed (invalid token, agent not found, etc.)
@@ -498,34 +645,68 @@ 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
       state.saveState(workingDir, {
-        agent_id: requestedId,
+        agent_id: agentId,
+        name: registrationResult.agent_name || agentId,
         owner,
-        token: result.token,
-        registered_at: result.registered_at,
+        token: registrationResult.connect_token!,
+        registered_at: new Date().toISOString(),
       });
 
       return {
-        ...result,
-        mode: "registered",
-        message: `Registered as ${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.`,
       };
     }
 
@@ -534,15 +715,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": {
@@ -563,7 +745,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": {
@@ -575,7 +757,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": {
@@ -587,7 +769,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": {
@@ -598,41 +780,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
@@ -645,25 +827,58 @@ 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.");
+      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,
+      });
+      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);
     }
 
     default:

package/src/tools/tools.test.ts

@@ -26,11 +26,15 @@ const mockClient = {
   listAgents: vi.fn(),
   sendMessage: vi.fn(),
   getInbox: vi.fn(),
+  getPendingTasks: vi.fn(),
   markRead: vi.fn(),
   reply: vi.fn(),
   listChannels: vi.fn(),
   joinChannel: vi.fn(),
   leaveChannel: vi.fn(),
+  completeTask: vi.fn(),
+  acceptTask: vi.fn(),
+  declineTask: vi.fn(),
 } as unknown as ApiClient;
 
 // Mock context
@@ -43,6 +47,7 @@ function createMockContext(): ToolContext {
     },
     stopHeartbeat: vi.fn(),
     getWorkingDir: () => "/tmp/test-workdir",
+    getPushedItems: () => ({ tasks: [], messages: [] }),
   };
 }
 
@@ -89,14 +94,16 @@ describe("handleToolCall", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     context = createMockContext();
-    // Default mock for inbox (used by message wrapping)
+    // Default mocks for wrapping (used by wrapWithPendingItems)
     vi.mocked(mockClient.getInbox).mockResolvedValue({ messages: [], total: 0 });
+    vi.mocked(mockClient.getPendingTasks).mockResolvedValue({ tasks: [], total: 0 });
   });
 
   describe("agent_register", () => {
     it("should register agent and set current agent ID", async () => {
       const mockResult = {
         agent_id: "test-agent",
+        name: "Test Agent",
         token: "test-token-uuid",
         model: "claude-opus-4.5",
         model_provider: "anthropic",