Bridging Global (AID) and Local (Zeroconf) Discovery

[nembal]

Following some excellent community feedback, I want to start a technical discussion on how to architect a clean bridge between AID and local discovery protocols like Zeroconf/mDNS.

I've written up the high-level "why" in a blog post—the "Two Phonebooks" analogy: [Link to your new blog post]

This thread is for the "how." How can we use the existing aid-py library to build a client that seamlessly resolves both global and local agents?

Here are some concrete implementation proposals to get the ball rolling:

1. Standardizing the uri for proto=local

To make this interoperable, we need a standard URI scheme within the AID record. I propose we use a format based on the standard DNS-SD service strings.

An AID record for a local Ollama server could look like this:

_agent.my-local-ollama.com IN TXT "v=aid1;p=local;uri=zeroconf:_http._tcp"

An application would see this and know it needs to perform a local mDNS query for an _http._tcp service, not make a standard web request.

2. Application-Level Handling (The Pattern)

The aid-py library correctly focuses on its core job: performing the DNS lookup and parsing the record. It shouldn't be bloated with mDNS dependencies.

Therefore, the responsibility for handling the local protocol falls to the application layer. A developer can build a simple resolver function on top of aid-py.

Here is a possible implementation pattern:

from aid_py import discover, AidError
from zeroconf import ServiceBrowser, Zeroconf, ZeroconfServiceTypes # User installs this dependency separately
import time

def resolve_agent_address(domain: str) -> str:
    """
    Resolves an agent's address, handling both global (via AID) 
    and local (via Zeroconf) discovery.
    """
    try:
        aid_result = discover(domain)
        
        if aid_result.record.proto == 'local':
            # The URI tells us what kind of local service to look for
            # e.g., "zeroconf:_http._tcp"
            service_type_str = aid_result.record.uri.split(":")[1] + ".local."
            print(f"Local discovery triggered. Searching for {service_type_str}...")

            # --- Zeroconf Discovery Logic ---
            # This is application-specific logic using the zeroconf library
            # (Note: This is a simplified example for clarity)
            zc = Zeroconf()
            discovered_services = []
            
            def on_service_state_change(zc, service_type, name, state_change):
                if state_change == "added":
                    info = zc.get_service_info(service_type, name)
                    if info:
                        addresses = ["%s:%d" % (addr, info.port) for addr in info.parsed_addresses()]
                        discovered_services.extend(addresses)

            browser = ServiceBrowser(zc, service_type_str, handlers=[on_service_state_change])
            time.sleep(1) # Wait a moment for discovery
            zc.close()

            if not discovered_services:
                raise ConnectionError(f"No local service found for {service_type_str}")

            # For this example, we just return the first discovered address
            return f"http://{discovered_services[0]}"
            # -------------------------------

        else:
            # For standard protocols, the URI is the address
            return aid_result.record.uri

    except AidError as e:
        # Pass up AID-specific errors
        raise e
    except Exception as e:
        # Handle other errors (e.g., Zeroconf failure)
        raise ConnectionError(f"Failed to resolve address for {domain}: {e}")

# --- Example Usage ---
# global_address = resolve_agent_address("supabase.agentcommunity.org") 
# print(f"Resolved global address: {global_address}")

# local_address = resolve_agent_address("my-local-ollama.com")
# print(f"Resolved local address: {local_address}")

3. The Security Boundary

This pattern reinforces a critical security consideration. The application must treat the switch from a globally-trusted resource (a DNSSEC-signed AID record) to a locally-discovered one as a security boundary crossing.

A client application implementing this pattern MUST:

• Require explicit user consent before connecting to a locally discovered service for the first time.
• Clearly indicate in logs and UI that the connection is to a local, unverified endpoint.

Questions for the community:

• Is the zeroconf:<service_type> URI scheme the right approach for proto=local?
• Does this application-level resolver pattern seem like a robust and secure way to handle the local/global bridge?
• Are there edge cases where this pattern might fall short?

Looking forward to hearing your thoughts.

[nembal]

This is fantastic, thank you so much! I really appreciate you taking the time to lay out those suggestions.

Based on your input, I've updated the example resolve_agent_address function to be much more resilient. It now includes:

1. An explicit trust_local=True flag to make local discovery a secure opt-in.
2. A configurable timeout parameter to handle slow discovery gracefully.
3. A strict regex check to validate the zeroconf: URI format.
4. A warning to the user if multiple services are found, to address the name clash issue.

Here’s the revised code snippet incorporating your ideas:

import re
import time
from typing import Optional
from aid_py import discover, AidError
from zeroconf import ServiceBrowser, Zeroconf # Assumes user has installed this

def resolve_agent_address(domain: str, trust_local: bool = False, timeout: int = 3) -> Optional[str]:
    """
    Resolves an agent's address, handling both global (AID) 
    and local (Zeroconf) discovery.
    """
    try:
        aid_result = discover(domain)
        
        if aid_result.record.proto == 'zeroconf':
            if not trust_local:
                print("Warning: Local discovery required but not enabled. Pass trust_local=True to allow.")
                return None

            uri_match = re.match(r"^zeroconf:(_[a-zA-Z0-9.-]+._tcp)$", aid_result.record.uri)
            if not uri_match:
                raise ValueError(f"Invalid Zeroconf URI format: {aid_result.record.uri}")
            
            service_type = uri_match.group(1) + ".local."
            print(f"Local discovery triggered. Searching for {service_type} for {timeout}s...")

            discovered_services = []
            zc = Zeroconf()
            
            def on_service_state_change(zc, s_type, name, state_change):
                if state_change == "added":
                    info = zc.get_service_info(s_type, name)
                    if info:
                        addresses = [f"http://{addr}:{info.port}" for addr in info.parsed_addresses()]
                        discovered_services.extend(addresses)

            browser = ServiceBrowser(zc, service_type, handlers=[on_service_state_change])
            time.sleep(timeout)
            zc.close()

            if not discovered_services:
                raise ConnectionError(f"No local service found for {service_type}")

            if len(discovered_services) > 1:
                print(f"Warning: Found multiple services: {discovered_services}. Using the first one.")
            
            return discovered_services[0]
        else:
            return aid_result.record.uri

    except AidError as e:
        raise e
    except Exception as e:
        raise ConnectionError(f"Failed to resolve address for {domain}: {e}")

Your point about officially locking down the format is crucial for the standard. To make sure we capture this properly and open it up for wider community discussion, I've created an issue for the zeroconf proposal here:

• Proposal: Add 'zeroconf' as an official protocol for local network discovery (Issue #28)

In fact, your feedback was so helpful it inspired me to open a few more issues to think about the future of the protocol. I've drafted proposals for adding support for other common protocols like gRPC, WebSockets, and even Bluetooth Low Energy (BLE), all as separate issues.

Thanks again for the fantastic input! If any other ideas come up pls just let us know here