agenthub-multiagent-mcp 1.1.5 → 1.4.0

package/src/client.ts

@@ -28,6 +28,76 @@ export interface PendingTask {
   created_at: string;
 }
 
+// Ticket system types
+export interface TicketTask {
+  id: string;
+  org_id: string;
+  project_id: string;
+  epic_id?: string;
+  story_id?: string;
+  key: string;
+  type: string;
+  title: string;
+  description?: string;
+  status: string;
+  priority: string;
+  points?: number;
+  review_mode: string;
+  assignee_id?: string;
+  assigned_agent?: string;
+  claimed_by?: string;
+  labels?: string[];
+  sprint_id?: string;
+  due_date?: string;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface TicketTaskContext {
+  task: TicketTask;
+  story?: {
+    id: string;
+    title: string;
+    description?: string;
+    status: string;
+  };
+  epic?: {
+    id: string;
+    title: string;
+    description?: string;
+    status: string;
+  };
+  project?: {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+  };
+}
+
+export interface TaskCheckpoint {
+  id: string;
+  task_id: string;
+  task_key: string;
+  agent_id: string;
+  description: string;
+  status: string;
+  reviewed_by?: string;
+  review_notes?: string;
+  reviewed_at?: string;
+  created_at: string;
+}
+
+export interface CheckpointResponse {
+  id: string;
+  task_id: string;
+  task_key: string;
+  status: string;
+  slack_posted: boolean;
+  created_at: string;
+}
+
 export interface TaskCompletionResponse {
   task_id: string;
   elapsed_time: string;
@@ -150,11 +220,19 @@ export class ApiClient {
   async startWork(
     agentId: string,
     task: string,
-    project?: string
-  ): Promise<{ acknowledged: boolean; slack_posted: boolean }> {
+    project?: string,
+    taskId?: string
+  ): Promise<{
+    acknowledged: boolean;
+    slack_posted: boolean;
+    task_id?: string;
+    task_key?: string;
+    task_linked?: boolean;
+  }> {
     return this.request("POST", `/agents/${agentId}/start-work`, {
       task,
       project,
+      task_id: taskId,
     });
   }
 
@@ -294,4 +372,242 @@ export class ApiClient {
       reason,
     });
   }
+
+  // Ticket system methods (for agent integration)
+
+  async getAvailableTasks(params?: {
+    status?: string;
+    project_id?: string;
+    priority?: string;
+    required_type?: string;
+  }): Promise<{ tasks: TicketTask[]; total: number }> {
+    const query = new URLSearchParams();
+    if (params?.status) query.set("status", params.status);
+    if (params?.project_id) query.set("project_id", params.project_id);
+    if (params?.priority) query.set("priority", params.priority);
+    if (params?.required_type) query.set("required_type", params.required_type);
+    const queryStr = query.toString() ? `?${query}` : "";
+    return this.request("GET", `/agent-tickets/available${queryStr}`);
+  }
+
+  async getTicketTask(taskId: string): Promise<TicketTaskContext> {
+    return this.request("GET", `/agent-tickets/${taskId}`);
+  }
+
+  async claimTicketTask(
+    taskId: string,
+    agentId: string
+  ): Promise<{
+    success: boolean;
+    task: TicketTask;
+    task_id: string;
+    task_key: string;
+  }> {
+    return this.request("POST", `/agent-tickets/${taskId}/claim`, {
+      agent_id: agentId,
+    });
+  }
+
+  async createCheckpoint(
+    taskId: string,
+    agentId: string,
+    description: string
+  ): Promise<CheckpointResponse> {
+    return this.request("POST", `/agent-tickets/${taskId}/checkpoint`, {
+      agent_id: agentId,
+      description,
+    });
+  }
+
+  // Browser-based registration flow
+  async initRegistration(agentId?: string, agentName?: string): Promise<{
+    session_token: string;
+    dashboard_url: string;
+    expires_at: string;
+  }> {
+    return this.request("POST", "/agents/register-init", {
+      agent_id: agentId,
+      agent_name: agentName,
+    });
+  }
+
+  async pollRegistrationCallback(token: string): Promise<{
+    status: "pending" | "completed" | "expired";
+    agent_id?: string;
+    agent_name?: string;
+    agent_type?: string;
+    connect_token?: string;
+    expires_at?: string;
+  }> {
+    const url = `${this.baseUrl}/agents/register-callback/${token}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": this.apiKey,
+      },
+    });
+
+    if (response.status === 202) {
+      // Still pending
+      const data = await response.json() as { status: string; expires_at: string };
+      return { status: "pending", expires_at: data.expires_at };
+    }
+
+    if (response.status === 410) {
+      // Expired
+      return { status: "expired" };
+    }
+
+    if (!response.ok) {
+      const data = await response.json() as { message?: string };
+      throw new Error(data.message || `Request failed: ${response.status}`);
+    }
+
+    const data = await response.json() as {
+      status: string;
+      agent_id: string;
+      agent_name: string;
+      agent_type: string;
+      connect_token: string;
+    };
+
+    return {
+      status: "completed",
+      agent_id: data.agent_id,
+      agent_name: data.agent_name,
+      agent_type: data.agent_type,
+      connect_token: data.connect_token,
+    };
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  // Ticket creation methods
+
+  async createEpic(params: {
+    project_id: string;
+    title: string;
+    description?: string;
+    source_file?: string;
+  }): Promise<{ id: string; key: string }> {
+    return this.request("POST", `/projects/${params.project_id}/epics`, {
+      title: params.title,
+      description: params.description,
+      metadata: params.source_file ? JSON.stringify({ source_file: params.source_file }) : undefined,
+    });
+  }
+
+  async createStory(params: {
+    project_id: string;
+    epic_id?: string;
+    title: string;
+    description?: string;
+    required_type?: string;
+    labels?: string[];
+    order?: number;
+  }): Promise<{ id: string; key: string }> {
+    return this.request("POST", `/projects/${params.project_id}/stories`, {
+      epic_id: params.epic_id,
+      title: params.title,
+      description: params.description,
+      required_type: params.required_type,
+      labels: params.labels,
+      backlog_order: params.order,
+    });
+  }
+
+  async createTask(params: {
+    project_id: string;
+    story_id?: string;
+    epic_id?: string;
+    title: string;
+    description?: string;
+    required_type?: string;
+    labels?: string[];
+    order?: number;
+  }): Promise<{ id: string; key: string }> {
+    return this.request("POST", `/projects/${params.project_id}/tasks`, {
+      story_id: params.story_id,
+      epic_id: params.epic_id,
+      title: params.title,
+      description: params.description,
+      required_type: params.required_type,
+      labels: params.labels,
+      backlog_order: params.order,
+    });
+  }
+
+  async addComment(params: {
+    ticket_id: string;
+    body: string;
+  }): Promise<{ id: string }> {
+    return this.request("POST", `/tickets/${params.ticket_id}/comments`, {
+      body: params.body,
+    });
+  }
+
+  async updateTicketStatus(params: {
+    ticket_id: string;
+    status: string;
+    summary?: string;
+    files_changed?: string[];
+  }): Promise<{ success: boolean }> {
+    return this.request("PATCH", `/tasks/${params.ticket_id}`, {
+      status: params.status,
+      summary: params.summary,
+      files_changed: params.files_changed,
+    });
+  }
+
+  async uploadAttachment(params: {
+    ticket_id: string;
+    ticket_type: string;
+    ticket_key: string;
+    file_path: string;
+    description?: string;
+    agent_id?: string;
+  }): Promise<{
+    id: string;
+    url: string;
+    filename: string;
+    size: number;
+    mime_type: string;
+  }> {
+    const fs = await import("fs");
+    const FormData = (await import("form-data")).default;
+
+    const form = new FormData();
+    form.append("ticket_id", params.ticket_id);
+    form.append("ticket_type", params.ticket_type);
+    form.append("ticket_key", params.ticket_key);
+    form.append("file", fs.createReadStream(params.file_path));
+    if (params.description) form.append("description", params.description);
+    if (params.agent_id) form.append("agent_id", params.agent_id);
+
+    const response = await fetch(`${this.baseUrl}/attachments`, {
+      method: "POST",
+      headers: {
+        "X-API-Key": this.apiKey,
+        ...form.getHeaders(),
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      body: form as any,
+    });
+
+    if (!response.ok) {
+      const error = await response.json() as { message?: string };
+      throw new Error(error.message || `Upload failed: ${response.status}`);
+    }
+
+    return response.json() as Promise<{
+      id: string;
+      url: string;
+      filename: string;
+      size: number;
+      mime_type: string;
+    }>;
+  }
 }

package/src/heartbeat.ts

@@ -1,8 +1,13 @@
 /**
  * Background heartbeat manager with enhanced logging for pending tasks/messages
+ * and automatic reconnection on failures.
  */
 
 import { ApiClient } from "./client.js";
+import { AgentState } from "./state.js";
+
+// Reconnection callback type
+export type ReconnectCallback = () => Promise<AgentState | null>;
 
 export class HeartbeatManager {
   private client: ApiClient;
@@ -13,16 +18,34 @@ export class HeartbeatManager {
   private lastUnreadMessages = 0;
   private heartbeatCount = 0;
 
+  // Retry state
+  private consecutiveFailures = 0;
+  private backoffMs = 1000; // Start at 1 second
+  private readonly maxBackoffMs = 30000; // Cap at 30 seconds
+  private readonly failuresBeforeReconnect = 3;
+  private reconnectCallback?: ReconnectCallback;
+  private isReconnecting = false;
+
   constructor(client: ApiClient) {
     this.client = client;
   }
 
+  /**
+   * Set callback for reconnection attempts
+   */
+  setReconnectCallback(callback: ReconnectCallback): void {
+    this.reconnectCallback = callback;
+  }
+
   start(agentId: string): void {
     this.stop(); // Clear any existing interval
     this.agentId = agentId;
     this.heartbeatCount = 0;
     this.lastPendingTasks = 0;
     this.lastUnreadMessages = 0;
+    this.consecutiveFailures = 0;
+    this.backoffMs = 1000;
+    this.isReconnecting = false;
 
     // Send heartbeat every 30 seconds
     this.intervalId = setInterval(async () => {
@@ -31,12 +54,12 @@ export class HeartbeatManager {
       try {
         await this.sendHeartbeat();
       } catch (error) {
-        console.error("Heartbeat failed:", error);
+        await this.handleHeartbeatFailure(error);
       }
     }, 30_000);
 
     // Send initial heartbeat
-    this.sendHeartbeat();
+    this.sendHeartbeat().catch((error) => this.handleHeartbeatFailure(error));
   }
 
   stop(): void {
@@ -57,42 +80,102 @@ export class HeartbeatManager {
 
   setStatus(status: "online" | "busy"): void {
     this.status = status;
-    this.sendHeartbeat();
+    this.sendHeartbeat().catch((error) => this.handleHeartbeatFailure(error));
   }
 
   private async sendHeartbeat(): Promise<void> {
     if (!this.agentId) return;
 
-    try {
-      const response = await this.client.heartbeat(this.agentId, this.status);
-      this.heartbeatCount++;
+    const response = await this.client.heartbeat(this.agentId, this.status);
 
-      const { pending_tasks_count, unread_messages_count } = response;
+    // Success - reset failure state
+    this.consecutiveFailures = 0;
+    this.backoffMs = 1000;
+    this.heartbeatCount++;
 
-      // Log if there are new pending tasks
-      if (pending_tasks_count > 0 && pending_tasks_count !== this.lastPendingTasks) {
-        console.error(`\n🔔 [AgentHub] You have ${pending_tasks_count} pending task(s) waiting! Use get_pending_tasks to view them.\n`);
-      }
+    const { pending_tasks_count, unread_messages_count } = response;
 
-      // Log if there are new unread messages
-      if (unread_messages_count > 0 && unread_messages_count !== this.lastUnreadMessages) {
-        console.error(`\n📬 [AgentHub] You have ${unread_messages_count} unread message(s)! Use check_inbox to read them.\n`);
+    // Log if there are new pending tasks
+    if (pending_tasks_count > 0 && pending_tasks_count !== this.lastPendingTasks) {
+      console.error(`\n🔔 [AgentHub] You have ${pending_tasks_count} pending task(s) waiting! Use get_pending_tasks to view them.\n`);
+    }
+
+    // Log if there are new unread messages
+    if (unread_messages_count > 0 && unread_messages_count !== this.lastUnreadMessages) {
+      console.error(`\n📬 [AgentHub] You have ${unread_messages_count} unread message(s)! Use check_inbox to read them.\n`);
+    }
+
+    // Periodic reminder every 5 heartbeats (2.5 minutes) if there are pending items
+    if (this.heartbeatCount % 5 === 0) {
+      if (pending_tasks_count > 0 || unread_messages_count > 0) {
+        const parts = [];
+        if (pending_tasks_count > 0) parts.push(`${pending_tasks_count} pending task(s)`);
+        if (unread_messages_count > 0) parts.push(`${unread_messages_count} unread message(s)`);
+        console.error(`\n⏰ [AgentHub] Reminder: You have ${parts.join(" and ")}.\n`);
       }
+    }
+
+    this.lastPendingTasks = pending_tasks_count;
+    this.lastUnreadMessages = unread_messages_count;
+  }
+
+  private async handleHeartbeatFailure(error: unknown): Promise<void> {
+    this.consecutiveFailures++;
+    console.error(`[AgentHub] Heartbeat failed (attempt ${this.consecutiveFailures}):`, error);
 
-      // Periodic reminder every 5 heartbeats (2.5 minutes) if there are pending items
-      if (this.heartbeatCount % 5 === 0) {
-        if (pending_tasks_count > 0 || unread_messages_count > 0) {
-          const parts = [];
-          if (pending_tasks_count > 0) parts.push(`${pending_tasks_count} pending task(s)`);
-          if (unread_messages_count > 0) parts.push(`${unread_messages_count} unread message(s)`);
-          console.error(`\n⏰ [AgentHub] Reminder: You have ${parts.join(" and ")}.\n`);
-        }
+    // Check if we should attempt full reconnection
+    if (this.consecutiveFailures >= this.failuresBeforeReconnect && !this.isReconnecting) {
+      await this.attemptReconnection();
+    } else {
+      // Schedule retry with exponential backoff
+      this.scheduleRetry();
+    }
+  }
+
+  private scheduleRetry(): void {
+    console.error(`[AgentHub] Retrying heartbeat in ${this.backoffMs}ms...`);
+
+    setTimeout(async () => {
+      if (!this.agentId) return;
+
+      try {
+        await this.sendHeartbeat();
+        console.error("[AgentHub] Heartbeat recovered!");
+      } catch (error) {
+        await this.handleHeartbeatFailure(error);
       }
+    }, this.backoffMs);
+
+    // Increase backoff for next failure (exponential with cap)
+    this.backoffMs = Math.min(this.backoffMs * 2, this.maxBackoffMs);
+  }
+
+  private async attemptReconnection(): Promise<void> {
+    if (!this.reconnectCallback) {
+      console.error("[AgentHub] No reconnect callback configured, continuing retries...");
+      this.scheduleRetry();
+      return;
+    }
+
+    this.isReconnecting = true;
+    console.error("[AgentHub] Attempting full reconnection...");
 
-      this.lastPendingTasks = pending_tasks_count;
-      this.lastUnreadMessages = unread_messages_count;
+    try {
+      const state = await this.reconnectCallback();
+      if (state) {
+        this.agentId = state.agent_id;
+        this.consecutiveFailures = 0;
+        this.backoffMs = 1000;
+        this.isReconnecting = false;
+        console.error(`[AgentHub] Reconnected successfully as ${state.agent_id}`);
+      } else {
+        throw new Error("No state available for reconnection");
+      }
     } catch (error) {
-      console.error("Heartbeat failed:", error);
+      console.error("[AgentHub] Reconnection failed:", error);
+      this.isReconnecting = false;
+      this.consecutiveFailures = 0; // Reset to try again after more failures
+      this.scheduleRetry();
     }
   }
 

package/src/index.ts

@@ -10,11 +10,14 @@ import {
 import { ApiClient } from "./client.js";
 import { registerTools, handleToolCall } from "./tools/index.js";
 import { HeartbeatManager } from "./heartbeat.js";
+import { WebSocketClient } from "./websocket.js";
+import * as state from "./state.js";
 
 // Environment configuration
 const AGENTHUB_URL = process.env.AGENTHUB_URL || "https://agenthub.contetial.com";
 const AGENTHUB_API_KEY = process.env.AGENTHUB_API_KEY || "";
 const AGENTHUB_AGENT_ID = process.env.AGENTHUB_AGENT_ID || "";
+const AGENTHUB_AUTO_RECONNECT = process.env.AGENTHUB_AUTO_RECONNECT !== "false"; // Enabled by default
 
 // Validate configuration
 if (!AGENTHUB_API_KEY) {
@@ -28,14 +31,61 @@ const client = new ApiClient(AGENTHUB_URL, AGENTHUB_API_KEY);
 // Initialize heartbeat manager
 const heartbeat = new HeartbeatManager(client);
 
-// Track current agent ID
+// Initialize WebSocket client for push notifications
+const wsClient = new WebSocketClient(AGENTHUB_URL, AGENTHUB_API_KEY);
+
+// Track current agent ID and working directory
 let currentAgentId = AGENTHUB_AGENT_ID;
+const workingDir = process.cwd();
+
+/**
+ * Attempt to reconnect using stored state
+ */
+async function attemptReconnect(): Promise<state.AgentState | null> {
+  const existingState = state.loadState(workingDir);
+  if (!existingState) {
+    return null;
+  }
+
+  const owner = state.getCurrentOwner();
+  if (existingState.owner !== owner) {
+    console.error("[AgentHub] State file belongs to different user, skipping auto-reconnect");
+    return null;
+  }
+
+  try {
+    const result = await client.reconnectAgent(
+      existingState.agent_id,
+      existingState.token,
+      owner,
+      undefined, // model - keep existing
+      existingState.name
+    );
+
+    if (result.reconnected) {
+      currentAgentId = result.agent_id;
+      // Update state with any changes
+      state.saveState(workingDir, {
+        ...existingState,
+        name: result.name,
+      });
+      return existingState;
+    }
+  } catch (error) {
+    console.error("[AgentHub] Reconnect attempt failed:", error);
+  }
+
+  return null;
+}
+
+// Set up reconnect callback for heartbeat manager
+heartbeat.setReconnectCallback(attemptReconnect);
 
 // Create MCP server
 const server = new Server(
   {
     name: "agenthub",
-    version: "1.1.5",
+    version: "1.2.0",
   },
   {
     capabilities: {
@@ -61,9 +111,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       setCurrentAgentId: (id: string) => {
         currentAgentId = id;
         heartbeat.start(id);
+        wsClient.connect(id);
+      },
+      stopHeartbeat: () => {
+        heartbeat.stop();
+        wsClient.close();
       },
-      stopHeartbeat: () => heartbeat.stop(),
       getWorkingDir: () => process.cwd(),
+      getPushedItems: () => wsClient.getPushedItems(),
     });
 
     return {
@@ -91,11 +146,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // Graceful shutdown
 process.on("SIGINT", () => {
   heartbeat.stop();
+  wsClient.close();
   process.exit(0);
 });
 
 process.on("SIGTERM", () => {
   heartbeat.stop();
+  wsClient.close();
   process.exit(0);
 });
 
@@ -105,15 +162,31 @@ async function main() {
   await server.connect(transport);
   console.error("AgentHub MCP server running");
 
-  // Auto-register if agent ID is provided
+  // Auto-register if agent ID is provided via environment
   if (AGENTHUB_AGENT_ID) {
     try {
       await client.registerAgent(AGENTHUB_AGENT_ID);
       heartbeat.start(AGENTHUB_AGENT_ID);
+      wsClient.connect(AGENTHUB_AGENT_ID);
       console.error(`Auto-registered as agent: ${AGENTHUB_AGENT_ID}`);
     } catch (error) {
       console.error(`Failed to auto-register: ${error}`);
     }
+  } else if (AGENTHUB_AUTO_RECONNECT) {
+    // Try to auto-reconnect from stored state
+    const existingState = state.loadState(workingDir);
+    if (existingState) {
+      console.error(`[AgentHub] Found existing state for agent: ${existingState.agent_id}`);
+      const reconnected = await attemptReconnect();
+      if (reconnected) {
+        heartbeat.start(reconnected.agent_id);
+        wsClient.connect(reconnected.agent_id);
+        const displayName = reconnected.name || reconnected.agent_id;
+        console.error(`[AgentHub] Auto-reconnected as: ${displayName}`);
+      } else {
+        console.error("[AgentHub] Auto-reconnect failed, manual registration required");
+      }
+    }
   }
 }
 

package/src/state.ts

@@ -23,6 +23,7 @@ export interface AgentState {
   name?: string;
   owner: string;
   token: string;
+  agent_type?: string;
   last_task?: string;
   registered_at: string;
 }