Centralize port constants and make ports configurable

Replace hardcoded port numbers throughout the codebase with centralized
constants from agentex.lib.constants.ports. This eliminates scattered
magic numbers and makes all default ports easy to discover and change.

Port changes:
- Health check: 8080 -> 8719 (avoids common proxy port)
- Debug worker: 5678 -> 5688 (avoids debugpy default)
- Debug ACP: 5679 -> 5689 (debug worker + 1)
- Redis: 6379 -> 6389 (avoids standard Redis port)
- ACP/API/Temporal ports unchanged (already non-standard)

All ports remain overridable via their respective environment variables
(ACP_PORT, HEALTH_CHECK_PORT, AGENTEX_DEBUG_PORT, REDIS_URL, etc).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SWE Destroyer

src/agentex/_client.py

@@ -53,9 +53,11 @@
     "AsyncClient",
 ]
 
+from agentex.lib.constants.ports import AGENTEX_API_BASE_URL
+
 ENVIRONMENTS: Dict[str, str] = {
-    "production": "http://localhost:5003",
-    "development": "http://localhost:5003",
+    "production": AGENTEX_API_BASE_URL,
+    "development": AGENTEX_API_BASE_URL,
 }
 
 

src/agentex/lib/cli/commands/agents.py

@@ -11,6 +11,7 @@
 
 from agentex import Agentex
 from agentex.lib.cli.debug import DebugMode, DebugConfig
+from agentex.lib.constants.ports import DEBUG_PORT
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.cli.utils.cli_utils import handle_questionary_cancellation
 from agentex.lib.sdk.config.validation import (
@@ -269,7 +270,7 @@ def run(
     debug: bool = typer.Option(False, help="Enable debug mode for both worker and ACP (disables auto-reload)"),
     debug_worker: bool = typer.Option(False, help="Enable debug mode for temporal worker only"),
     debug_acp: bool = typer.Option(False, help="Enable debug mode for ACP server only"),
-    debug_port: int = typer.Option(5678, help="Port for remote debugging (worker uses this, ACP uses port+1)"),
+    debug_port: int = typer.Option(DEBUG_PORT, help="Port for remote debugging (worker uses this, ACP uses port+1)"),
     wait_for_debugger: bool = typer.Option(False, help="Wait for debugger to attach before starting"),
 ) -> None:
     """

src/agentex/lib/cli/debug/debug_config.py

@@ -5,11 +5,13 @@
 import socket
 from enum import Enum
 
+from agentex.lib.constants.ports import DEBUG_ACP_PORT, DEBUG_PORT
 from agentex.lib.utils.model_utils import BaseModel
 
 
 class DebugMode(str, Enum):
     """Debug mode options"""
+
     WORKER = "worker"
     ACP = "acp"
     BOTH = "both"
@@ -18,91 +20,73 @@ class DebugMode(str, Enum):
 
 class DebugConfig(BaseModel):
     """Configuration for debug mode"""
-    
+
     enabled: bool = False
     mode: DebugMode = DebugMode.NONE
-    port: int = 5678
+    port: int = DEBUG_PORT
     wait_for_attach: bool = False
     auto_port: bool = True  # Automatically find available port if specified port is busy
-    
+
     @classmethod
     def create_worker_debug(
-        cls, 
-        port: int = 5678, 
-        wait_for_attach: bool = False,
-        auto_port: bool = True
+        cls, port: int = DEBUG_PORT, wait_for_attach: bool = False, auto_port: bool = True
     ) -> "DebugConfig":
         """Create debug config for worker debugging"""
-        return cls(
-            enabled=True,
-            mode=DebugMode.WORKER,
-            port=port,
-            wait_for_attach=wait_for_attach,
-            auto_port=auto_port
-        )
-    
+        return cls(enabled=True, mode=DebugMode.WORKER, port=port, wait_for_attach=wait_for_attach, auto_port=auto_port)
+
     @classmethod
     def create_acp_debug(
-        cls, 
-        port: int = 5679, 
-        wait_for_attach: bool = False,
-        auto_port: bool = True
+        cls, port: int = DEBUG_ACP_PORT, wait_for_attach: bool = False, auto_port: bool = True
     ) -> "DebugConfig":
         """Create debug config for ACP debugging"""
-        return cls(
-            enabled=True,
-            mode=DebugMode.ACP,
-            port=port,
-            wait_for_attach=wait_for_attach,
-            auto_port=auto_port
-        )
-    
+        return cls(enabled=True, mode=DebugMode.ACP, port=port, wait_for_attach=wait_for_attach, auto_port=auto_port)
+
     @classmethod
     def create_both_debug(
-        cls, 
-        worker_port: int = 5678,
-        _acp_port: int = 5679,
+        cls,
+        worker_port: int = DEBUG_PORT,
+        _acp_port: int = DEBUG_ACP_PORT,
         wait_for_attach: bool = False,
-        auto_port: bool = True
+        auto_port: bool = True,
     ) -> "DebugConfig":
         """Create debug config for both worker and ACP debugging"""
         return cls(
             enabled=True,
             mode=DebugMode.BOTH,
             port=worker_port,  # Primary port for worker
             wait_for_attach=wait_for_attach,
-            auto_port=auto_port
+            auto_port=auto_port,
         )
-    
+
     def should_debug_worker(self) -> bool:
         """Check if worker should be debugged"""
         return self.enabled and self.mode in (DebugMode.WORKER, DebugMode.BOTH)
-    
+
     def should_debug_acp(self) -> bool:
         """Check if ACP should be debugged"""
         return self.enabled and self.mode in (DebugMode.ACP, DebugMode.BOTH)
-    
+
     def get_worker_port(self) -> int:
         """Get port for worker debugging"""
         return self.port
-    
+
     def get_acp_port(self) -> int:
         """Get port for ACP debugging"""
         if self.mode == DebugMode.BOTH:
             return self.port + 1  # Use port + 1 for ACP when debugging both
         return self.port
 
 
-def find_available_port(start_port: int = 5678, max_attempts: int = 10) -> int:
+def find_available_port(start_port: int = DEBUG_PORT, max_attempts: int = 10) -> int:
     """Find an available port starting from start_port"""
     for port in range(start_port, start_port + max_attempts):
         try:
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-                s.bind(('localhost', port))
+                s.bind(("localhost", port))
                 return port
         except OSError:
             continue
-    
+
     # If we can't find an available port, just return the start port
     # and let the debug server handle the error
     return start_port
@@ -112,4 +96,4 @@ def resolve_debug_port(config: DebugConfig, target_port: int) -> int:
     """Resolve the actual port to use for debugging"""
     if config.auto_port:
         return find_available_port(target_port)
-    return target_port 
+    return target_port

src/agentex/lib/cli/handlers/cleanup_handlers.py

@@ -4,6 +4,7 @@
 from rich.console import Console
 
 from agentex import Agentex
+from agentex.lib.constants.ports import TEMPORAL_ADDRESS as DEFAULT_TEMPORAL_ADDRESS
 from agentex.lib.utils.logging import make_logger
 
 # Import Temporal client for direct workflow termination
@@ -19,88 +20,84 @@
 def should_cleanup_on_restart() -> bool:
     """
     Check if cleanup should be performed on restart.
-    
+
     Returns True if:
     - ENVIRONMENT=development, OR
     - AUTO_CLEANUP_ON_RESTART=true
     """
     env = os.getenv("ENVIRONMENT", "").lower()
     auto_cleanup = os.getenv("AUTO_CLEANUP_ON_RESTART", "true").lower()
-    
+
     return env == "development" or auto_cleanup == "true"
 
 
-def cleanup_agent_workflows(
-    agent_name: str,
-    force: bool = False,
-    development_only: bool = True
-) -> None:
+def cleanup_agent_workflows(agent_name: str, force: bool = False, development_only: bool = True) -> None:
     """
     Clean up all running workflows for an agent during development.
-    
+
     This cancels (graceful) all running tasks for the specified agent.
     When force=True, directly terminates workflows via Temporal client.
-    
+
     Args:
         agent_name: Name of the agent to cleanup workflows for
         force: If True, directly terminate workflows via Temporal client
         development_only: Only perform cleanup in development environment
     """
-    
+
     # Safety check - only run in development mode by default
     if development_only and not force and not should_cleanup_on_restart():
         logger.warning("Cleanup skipped - not in development mode. Use --force to override.")
         return
-    
+
     method = "terminate (direct)" if force else "cancel (via agent)"
     console.print(f"[blue]Cleaning up workflows for agent '{agent_name}' using {method}...[/blue]")
-    
+
     try:
         client = Agentex()
-        
+
         # Get all running tasks
         if agent_name:
             all_tasks = client.tasks.list(agent_name=agent_name)
         else:
             all_tasks = client.tasks.list()
-        running_tasks = [task for task in all_tasks if hasattr(task, 'status') and task.status == "RUNNING"]
-        
+        running_tasks = [task for task in all_tasks if hasattr(task, "status") and task.status == "RUNNING"]
+
         if not running_tasks:
             console.print("[yellow]No running tasks found[/yellow]")
             return
-        
+
         console.print(f"[blue]Cleaning up {len(running_tasks)} running task(s) for agent '{agent_name}'...[/blue]")
-        
+
         successful_cleanups = 0
         total_tasks = len(running_tasks)
-        
+
         for task in running_tasks:
             task_cleanup_success = False
-            
+
             if force:
                 # Force mode: Do both graceful RPC cancellation AND direct Temporal termination
                 rpc_success = False
                 temporal_success = False
-                
+
                 try:
                     # First: Graceful cancellation via agent RPC (handles database/agent cleanup)
                     cleanup_single_task(client, agent_name, task.id)
                     logger.debug(f"Completed RPC cancellation for task {task.id}")
                     rpc_success = True
                 except Exception as e:
                     logger.warning(f"RPC cancellation failed for task {task.id}: {e}")
-                
+
                 try:
                     # Second: Direct Temporal termination (ensures workflow is forcefully stopped)
                     asyncio.run(cleanup_single_task_direct(task.id))
                     logger.debug(f"Completed Temporal termination for task {task.id}")
                     temporal_success = True
                 except Exception as e:
                     logger.warning(f"Temporal termination failed for task {task.id}: {e}")
-                
+
                 # Count as success if either operation succeeded
                 task_cleanup_success = rpc_success or temporal_success
-                
+
             else:
                 # Normal mode: Only graceful cancellation via agent RPC
                 try:
@@ -109,21 +106,25 @@ def cleanup_agent_workflows(
                 except Exception as e:
                     logger.error(f"Failed to cleanup task {task.id}: {e}")
                     task_cleanup_success = False
-            
+
             if task_cleanup_success:
                 successful_cleanups += 1
                 logger.debug(f"Successfully cleaned up task {task.id}")
             else:
                 logger.error(f"Failed to cleanup task {task.id}")
                 # Don't increment successful_cleanups for actual failures
-        
+
         if successful_cleanups == total_tasks:
-            console.print(f"[green]✓ Successfully cleaned up all {successful_cleanups} task(s) for agent '{agent_name}'[/green]")
+            console.print(
+                f"[green]✓ Successfully cleaned up all {successful_cleanups} task(s) for agent '{agent_name}'[/green]"
+            )
         elif successful_cleanups > 0:
-            console.print(f"[yellow]⚠ Successfully cleaned up {successful_cleanups}/{total_tasks} task(s) for agent '{agent_name}'[/yellow]")
+            console.print(
+                f"[yellow]⚠ Successfully cleaned up {successful_cleanups}/{total_tasks} task(s) for agent '{agent_name}'[/yellow]"
+            )
         else:
             console.print(f"[red]✗ Failed to cleanup any tasks for agent '{agent_name}'[/red]")
-        
+
     except Exception as e:
         console.print(f"[red]Agent workflow cleanup failed: {str(e)}[/red]")
         logger.exception("Agent workflow cleanup failed")
@@ -133,51 +134,47 @@ def cleanup_agent_workflows(
 async def cleanup_single_task_direct(task_id: str) -> None:
     """
     Directly terminate a workflow using Temporal client.
-    
+
     Args:
         task_id: ID of the task (used as workflow_id)
     """
     if TemporalClient is None:
         raise ImportError("temporalio package not available for direct workflow termination")
-    
+
     try:
         # Connect to Temporal server (assumes default localhost:7233)
-        client = await TemporalClient.connect("localhost:7233")  # type: ignore
-        
+        client = await TemporalClient.connect(DEFAULT_TEMPORAL_ADDRESS)  # type: ignore
+
         # Get workflow handle and terminate
         handle = client.get_workflow_handle(workflow_id=task_id)  # type: ignore
         await handle.terminate()  # type: ignore
-        
+
         logger.debug(f"Successfully terminated workflow {task_id} via Temporal client")
-        
+
     except Exception as e:
         # Check if the workflow was already completed - this is actually a success case
         if "workflow execution already completed" in str(e).lower():
             logger.debug(f"Workflow {task_id} was already completed - no termination needed")
             return  # Don't raise an exception for this case
-        
+
         logger.error(f"Failed to terminate workflow {task_id} via Temporal client: {e}")
         raise
 
 
 def cleanup_single_task(client: Agentex, agent_name: str, task_id: str) -> None:
     """
     Clean up a single task/workflow using agent RPC cancel method.
-    
+
     Args:
-        client: Agentex client instance  
+        client: Agentex client instance
         agent_name: Name of the agent that owns the task
         task_id: ID of the task to cleanup
     """
     try:
         # Use the agent RPC method to cancel the task
-        client.agents.rpc_by_name(
-            agent_name=agent_name,
-            method="task/cancel",
-            params={"task_id": task_id}
-        )
+        client.agents.rpc_by_name(agent_name=agent_name, method="task/cancel", params={"task_id": task_id})
         logger.debug(f"Successfully cancelled task {task_id} via agent '{agent_name}'")
-    
+
     except Exception as e:
         logger.warning(f"RPC task/cancel failed for task {task_id}: {e}")
-        raise
+        raise