Centralize port defaults and make ports configurable

- Create src/agentex/lib/constants/ports.py as single source of truth for
  all default port numbers (ACP, API, Temporal, Redis, health check, debug)
- Replace all hardcoded port literals across the codebase with constants
- Make ports overridable via environment variables (TEMPORAL_ADDRESS,
  REDIS_URL, ACP_PORT, HEALTH_CHECK_PORT, AGENTEX_DEBUG_PORT)
- Update Dockerfile templates to use ARG/ENV pattern for ACP_PORT so
  the port can be configured at Docker build time
- Change health check port default from 8080 (too generic) to 9718
- Update run_handlers to read TEMPORAL_ADDRESS and REDIS_URL from env
  before falling back to defaults
- Update cleanup_handlers to use configurable Temporal address instead
  of hardcoded localhost:7233

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

Author: SWE Destroyer

src/agentex/_client.py

@@ -29,6 +29,7 @@
     SyncAPIClient,
     AsyncAPIClient,
 )
+from .lib.constants.ports import DEFAULT_AGENTEX_API_BASE_URL
 
 if TYPE_CHECKING:
     from .resources import spans, tasks, agents, events, states, tracker, messages, deployment_history
@@ -54,8 +55,8 @@
 ]
 
 ENVIRONMENTS: Dict[str, str] = {
-    "production": "http://localhost:5003",
-    "development": "http://localhost:5003",
+    "production": DEFAULT_AGENTEX_API_BASE_URL,
+    "development": DEFAULT_AGENTEX_API_BASE_URL,
 }
 
 

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

@@ -5,11 +5,13 @@
 import socket
 from enum import Enum
 
+from agentex.lib.constants.ports import DEFAULT_DEBUG_ACP_PORT, DEFAULT_DEBUG_WORKER_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 = DEFAULT_DEBUG_WORKER_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 = DEFAULT_DEBUG_WORKER_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 = DEFAULT_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 = DEFAULT_DEBUG_WORKER_PORT,
+        _acp_port: int = DEFAULT_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 = DEFAULT_DEBUG_WORKER_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

@@ -5,6 +5,7 @@
 
 from agentex import Agentex
 from agentex.lib.utils.logging import make_logger
+from agentex.lib.constants.ports import DEFAULT_TEMPORAL_ADDRESS
 
 # Import Temporal client for direct workflow termination
 try:
@@ -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
-        
+        temporal_address = os.environ.get("TEMPORAL_ADDRESS", DEFAULT_TEMPORAL_ADDRESS)
+        client = await TemporalClient.connect(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

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

@@ -11,6 +11,7 @@
 from rich.console import Console
 
 from agentex.lib.utils.logging import make_logger
+from agentex.lib.constants.ports import DEFAULT_ACP_PORT
 from agentex.lib.cli.utils.exceptions import HelmError, DeploymentError
 from agentex.lib.cli.utils.path_utils import PathResolutionError, calculate_docker_acp_module
 from agentex.lib.environment_variables import EnvVarKeys
@@ -239,12 +240,19 @@ def add_acp_command_to_helm_values(helm_values: dict[str, Any], manifest: AgentM
     try:
         docker_acp_module = calculate_docker_acp_module(manifest, manifest_path)
         # Create the uvicorn command with the correct module path
-        helm_values["command"] = ["uvicorn", f"{docker_acp_module}:acp", "--host", "0.0.0.0", "--port", "8000"]
+        helm_values["command"] = [
+            "uvicorn",
+            f"{docker_acp_module}:acp",
+            "--host",
+            "0.0.0.0",
+            "--port",
+            str(DEFAULT_ACP_PORT),
+        ]
         logger.info(f"Using dynamic ACP command: uvicorn {docker_acp_module}:acp")
     except (PathResolutionError, Exception) as e:
         # Fallback to default command structure
         logger.warning(f"Could not calculate dynamic ACP module ({e}), using default: project.acp")
-        helm_values["command"] = ["uvicorn", "project.acp:acp", "--host", "0.0.0.0", "--port", "8000"]
+        helm_values["command"] = ["uvicorn", "project.acp:acp", "--host", "0.0.0.0", "--port", str(DEFAULT_ACP_PORT)]
 
 
 def merge_deployment_configs(