Fix A2A agent card advertising unroutable wildcard address

pkg/a2a/server.go

@@ -23,6 +23,19 @@ import (
 	"github.com/docker/cagent/pkg/version"
 )
 
+// routableAddr replaces wildcard listen addresses (like "0.0.0.0" or "::") with
+// "localhost" so the agent card URL is actually usable by clients.
+func routableAddr(addr string) string {
+	host, port, err := net.SplitHostPort(addr)
+	if err != nil {
+		return addr
+	}
+	if host == "" || host == "0.0.0.0" || host == "::" {
+		return net.JoinHostPort("localhost", port)
+	}
+	return addr
+}
+
 func Run(ctx context.Context, agentFilename, agentName string, runConfig *config.RuntimeConfig, ln net.Listener) error {
 	slog.Debug("Starting A2A server", "agent", agentName, "addr", ln.Addr().String())
 
@@ -46,7 +59,7 @@ func Run(ctx context.Context, agentFilename, agentName string, runConfig *config
 		return fmt.Errorf("failed to create ADK agent adapter: %w", err)
 	}
 
-	baseURL := &url.URL{Scheme: "http", Host: ln.Addr().String()}
+	baseURL := &url.URL{Scheme: "http", Host: routableAddr(ln.Addr().String())}
 
 	slog.Debug("A2A server listening", "url", baseURL.String())
 

pkg/a2a/server_test.go

@@ -0,0 +1,33 @@
+package a2a
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestRoutableAddr(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		addr string
+		want string
+	}{
+		{"ipv6 wildcard", "[::]:8080", "localhost:8080"},
+		{"ipv4 wildcard", "0.0.0.0:8080", "localhost:8080"},
+		{"empty host", ":8080", "localhost:8080"},
+		{"localhost stays", "localhost:8080", "localhost:8080"},
+		{"ipv4 loopback stays", "127.0.0.1:8080", "127.0.0.1:8080"},
+		{"specific ip stays", "192.168.1.1:9090", "192.168.1.1:9090"},
+		{"hostname stays", "my-host:8080", "my-host:8080"},
+		{"invalid addr returned as-is", "not-a-host-port", "not-a-host-port"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			assert.Equal(t, tt.want, routableAddr(tt.addr))
+		})
+	}
+}

pkg/server/listen.go

@@ -36,5 +36,5 @@ func listenUnix(ctx context.Context, path string) (net.Listener, error) {
 
 func listenTCP(ctx context.Context, addr string) (net.Listener, error) {
 	var lc net.ListenConfig
-	return lc.Listen(ctx, "tcp", addr)
+	return lc.Listen(ctx, "tcp4", addr)
 }