Description

The agent-runtime repository includes a port allocation utility in its foundation shared libraries, but it lacks proper resource lifecycle management. When agents are frequently deployed and stopped (as is common in dev/test environments and CI pipelines), port conflicts can arise:

1. Ports are allocated but not tracked per-tenant or per-agent: If an agent crashes or is force-stopped, its allocated port may remain in the "in-use" set and never be reclaimed, leading to resource exhaustion.
2. No port range partitioning: In a multi-tenant setup, two tenants could be allocated the same port for different agents, causing silent conflicts when agents bind to 0.0.0.0.
3. No graceful release on agent stop: The stop() or teardown() lifecycle hooks of deployers don't explicitly call a port release method.

Expected Behavior

1. Range-based allocation: Support defining non-overlapping port ranges per tenant or space (e.g., Tenant-A: 50000–50500, Tenant-B: 50501–51000) to prevent cross-tenant port conflicts.
2. Reservation tracking per agent: Each allocated port should be associated with an agent ID + deployment ID, so it can be deterministically released.
3. Automatic release on agent stop: When Deployer.stop() or Deployer.teardown() is called, the port allocator should be notified to release the port back to the pool.
4. Grace period before reuse: After release, a port should enter a RELEASING state for a configurable cooldown period (e.g., 30s) before being available for re-allocation, to avoid conflicts with lingering socket TIME_WAIT states.

Suggested Approach

1. Refactor PortAllocator into a stateful manager:
   • Data model: PortEntry(port, tenant_id, space_id, agent_id, status=IN_USE|RELEASING|FREE, released_at)
   • Use the existing SQLite handler for persistence so state survives runtime restarts
2. Add methods:
   • allocate(tenant_id, space_id, agent_id) -> int
   • release(agent_id) -> bool
   • get_allocated(tenant_id) -> list[PortEntry]
3. Wire port release into the deployer lifecycle:
   • Call port_allocator.release(agent_id) in SubprocessDeployer.stop(), DockerDeployer.stop(), and K8sDeployer.stop()
4. Expose a /api/v1/ports management endpoint (admin-only) for inspecting and manually releasing ports

Related components

• agent_runtime/common/utils/port.py — current port allocation logic
• agent_runtime/common/db/sqlite_handler.py — for port state persistence
• agent_runtime/deployer/*.py — all strategy deployers need lifecycle wiring
• agent_runtime/api/routes.py — new admin endpoint

Labels

enhancement, good first issue