tractor/ai/prompt-io/claude/20260414T163300Z_befedc49_prompt_io.raw.md

Add a prefer_addr() helper

Added transport preference selection to tractor/discovery/_api.py with two new functions:

_is_local_addr(addr: Address) -> bool

Determines whether an Address is reachable on the local host:

• UDSAddress: always returns True (filesystem-bound, inherently local)
• TCPAddress: checks if ._host is a loopback IP via ipaddress.ip_address().is_loopback, then falls back to comparing against the machine’s own interface IPs via socket.getaddrinfo(socket.gethostname(), None)

prefer_addr(addrs: list[UnwrappedAddress]) -> UnwrappedAddress

Selects the “best” transport address from a multihomed actor’s address list. Wraps each candidate via wrap_address() to get typed Address objects, then classifies into three tiers:

1. UDS (same-host guaranteed, lowest overhead)
2. TCP loopback / same-host IP (local network)
3. TCP remote (only option for distributed)

Within each tier, the last-registered (latest) entry is preferred. Falls back to addrs[-1] if no heuristic matches.

Integration

• Registrar.find_actor() in _registry.py: changed return type from UnwrappedAddress|None to list[UnwrappedAddress]|None — returns the full addr list so callers can apply transport preference.

• query_actor() in _api.py: now calls prefer_addr(addrs) on the list returned by Registrar.find_actor() instead of receiving a single pre-selected addr.

• wait_for_actor() in _api.py: replaced addrs[-1] with prefer_addr(addrs) for consistent transport selection.

Verification

All discovery tests pass (13/13 non-daemon). test_local.py and test_multi_program.py also pass (daemon fixture teardown failures are pre-existing and unrelated).