DevMode: improvements around feedback

.github/workflows/go.yml

@@ -8,6 +8,9 @@ on:
       - 'CHANGELOG.md'
   pull_request:
     branches: [ "main" ]
+    paths-ignore:
+      - 'README.md'
+      - 'CHANGELOG.md'
 
 permissions:
   contents: read

.github/workflows/upgrade-test.yml

@@ -8,6 +8,9 @@ on:
       - 'CHANGELOG.md'
   pull_request:
     branches: [ main ]
+    paths-ignore:
+      - 'README.md'
+      - 'CHANGELOG.md'
   workflow_dispatch:
 
 permissions:

cmd/agent.go

@@ -767,7 +767,7 @@ var agentTestCmd = &cobra.Command{
 		}
 		endpoint := fmt.Sprintf("%s/%s/%s", theproject.TransportURL, route, agentID)
 		if local {
-			port, _ := dev.FindAvailablePort(theproject)
+			port, _ := dev.FindAvailablePort(theproject, 0)
 			endpoint = fmt.Sprintf("http://127.0.0.1:%d/%s", port, agentID)
 		}
 

cmd/dev.go

@@ -75,11 +75,9 @@ Examples:
 		orgId := project.OrgId
 
 		port, _ := cmd.Flags().GetInt("port")
-		if port == 0 {
-			port, err = dev.FindAvailablePort(theproject)
-			if err != nil {
-				log.Fatal("failed to find available port: %s", err)
-			}
+		port, err = dev.FindAvailablePort(theproject, port)
+		if err != nil {
+			log.Fatal("failed to find available port: %s", err)
 		}
 
 		serverAddr, _ := cmd.Flags().GetString("server")

go.mod

@@ -16,6 +16,7 @@ require (
 	github.com/evanw/esbuild v0.25.0
 	github.com/fsnotify/fsnotify v1.7.0
 	github.com/google/uuid v1.6.0
+	github.com/lrstanley/bubblezone v1.0.0
 	github.com/marcozac/go-jsonc v0.1.1
 	github.com/mattn/go-isatty v0.0.20
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
@@ -35,8 +36,8 @@ require (
 	github.com/ProtonMail/go-crypto v1.1.5 // indirect
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.1 // indirect
-	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
+	github.com/charmbracelet/colorprofile v0.3.1 // indirect
+	github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
 	github.com/cloudflare/circl v1.6.0 // indirect
 	github.com/cyphar/filepath-securejoin v0.4.1 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect
@@ -132,9 +133,9 @@ require (
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	golang.org/x/net v0.38.0
-	golang.org/x/sync v0.12.0 // indirect
+	golang.org/x/sync v0.13.0 // indirect
 	golang.org/x/sys v0.32.0
-	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/text v0.24.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20250303144028-a0af3efb3deb // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250303144028-a0af3efb3deb // indirect
 	google.golang.org/grpc v1.71.0 // indirect

go.sum

@@ -43,8 +43,8 @@ github.com/charmbracelet/bubbles v0.20.0 h1:jSZu6qD8cRQ6k9OMfR1WlM+ruM8fkPWkHvQW
 github.com/charmbracelet/bubbles v0.20.0/go.mod h1:39slydyswPy+uVOHZ5x/GjwVAFkCsV8IIVy+4MhzwwU=
 github.com/charmbracelet/bubbletea v1.3.4 h1:kCg7B+jSCFPLYRA52SDZjr51kG/fMUEoPoZrkaDHyoI=
 github.com/charmbracelet/bubbletea v1.3.4/go.mod h1:dtcUCyCGEX3g9tosuYiut3MXgY/Jsv9nKVdibKKRRXo=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4pZI35227imm7yK2bGPcfpFEmuY1gc2YSTShr4iJBfs=
-github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
+github.com/charmbracelet/colorprofile v0.3.1 h1:k8dTHMd7fgw4bnFd7jXTLZrSU/CQrKnL3m+AxCzDz40=
+github.com/charmbracelet/colorprofile v0.3.1/go.mod h1:/GkGusxNs8VB/RSOh3fu0TJmQ4ICMMPApIIVn0KszZ0=
 github.com/charmbracelet/huh v0.6.0 h1:mZM8VvZGuE0hoDXq6XLxRtgfWyTI3b2jZNKh0xWmax8=
 github.com/charmbracelet/huh v0.6.0/go.mod h1:GGNKeWCeNzKpEOh/OJD8WBwTQjV3prFAtQPpLv+AVwU=
 github.com/charmbracelet/huh/spinner v0.0.0-20250313000648-36d9de46d64e h1:J8uxtAwJwvw0r5Wf+dfglLl/s+LcuUwj6VvoMyFw89U=
@@ -53,8 +53,8 @@ github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoF
 github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
 github.com/charmbracelet/x/ansi v0.8.0 h1:9GTq3xq9caJW8ZrBTe0LIe2fvfLR/bYXKTx2llXn7xE=
 github.com/charmbracelet/x/ansi v0.8.0/go.mod h1:wdYl/ONOLHLIVmQaxbIYEC/cRKOQyjTkowiI4blgS9Q=
-github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0GVL4jeHEwG5YOXDmi86oYw2yuYUGqz6a8sLwg0X8=
-github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
+github.com/charmbracelet/x/cellbuf v0.0.13 h1:/KBBKHuVRbq1lYx5BzEHBAFBP8VcQzJejZ/IA3iR28k=
+github.com/charmbracelet/x/cellbuf v0.0.13/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240815200342-61de596daa2b h1:MnAMdlwSltxJyULnrYbkZpp4k58Co7Tah3ciKhSNo0Q=
 github.com/charmbracelet/x/exp/golden v0.0.0-20240815200342-61de596daa2b/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
 github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 h1:qko3AQ4gK1MTS/de7F5hPGx6/k1u0w4TeYmBFwzYVP4=
@@ -152,6 +152,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/lrstanley/bubblezone v1.0.0 h1:bIpUaBilD42rAQwlg/4u5aTqVAt6DSRKYZuSdmkr8UA=
+github.com/lrstanley/bubblezone v1.0.0/go.mod h1:kcTekA8HE/0Ll2bWzqHlhA2c513KDNLW7uDfDP4Mly8=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
@@ -320,8 +322,8 @@ golang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
-golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sync v0.13.0 h1:AauUjRAJ9OSnvULf/ARrrVywoJDy0YS2AwQ98I37610=
+golang.org/x/sync v0.13.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -343,8 +345,8 @@ golang.org/x/term v0.30.0/go.mod h1:NYYFdzHoI5wRh/h5tDMdMqCqPJZEuNqVR5xJLd/n67g=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
-golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
+golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0=
+golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=

internal/dev/dev.go

@@ -56,12 +56,13 @@ func KillProjectServer(logger logger.Logger, projectServerCmd *exec.Cmd, pid int
 }
 
 func isPortAvailable(port int) bool {
-	listener, err := net.Listen("tcp4", fmt.Sprintf("0.0.0.0:%d", port))
+	timeout := time.Second
+	conn, err := net.DialTimeout("tcp", fmt.Sprintf("0.0.0.0:%d", port), timeout)
 	if err != nil {
-		return false
+		return true
 	}
-	listener.Close()
-	return true
+	defer conn.Close()
+	return false
 }
 
 func findAvailablePort() (int, error) {
@@ -73,7 +74,12 @@ func findAvailablePort() (int, error) {
 	return listener.Addr().(*net.TCPAddr).Port, nil
 }
 
-func FindAvailablePort(p project.ProjectContext) (int, error) {
+func FindAvailablePort(p project.ProjectContext, tryPort int) (int, error) {
+	if tryPort > 0 {
+		if isPortAvailable(tryPort) {
+			return tryPort, nil
+		}
+	}
 	if v, ok := os.LookupEnv("AGENTUITY_CLOUD_PORT"); ok && v != "" {
 		p, err := strconv.Atoi(v)
 		if err != nil {

internal/dev/server.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"math"
 	"net/http"
 	"net/http/httputil"
@@ -192,10 +193,37 @@ func (s *Server) connect(initial bool) {
 
 }
 
+type AgentWelcome struct {
+	project.AgentConfig
+	Welcome
+}
+
 type AgentsControlResponse struct {
-	ProjectID   string                `json:"projectId"`
-	ProjectName string                `json:"projectName"`
-	Agents      []project.AgentConfig `json:"agents"`
+	ProjectID   string         `json:"projectId"`
+	ProjectName string         `json:"projectName"`
+	Agents      []AgentWelcome `json:"agents"`
+}
+
+func (s *Server) getAgents(ctx context.Context, project *project.Project) (*AgentsControlResponse, error) {
+	var resp = &AgentsControlResponse{
+		ProjectID:   project.ProjectId,
+		ProjectName: project.Name,
+	}
+	welcome, err := s.getWelcome(ctx, s.port)
+	if err != nil {
+		return nil, err
+	}
+	for _, agent := range project.Agents {
+		var w Welcome
+		if welcome != nil {
+			w = welcome[agent.ID]
+		}
+		resp.Agents = append(resp.Agents, AgentWelcome{
+			AgentConfig: agent,
+			Welcome:     w,
+		})
+	}
+	return resp, nil
 }
 
 func sendCORSHeaders(headers http.Header) {
@@ -226,18 +254,14 @@ func (s *Server) handleStream(w http.ResponseWriter, r *http.Request) {
 		return
 	case "/_agents":
 		sendCORSHeaders(w.Header())
-		buf, err := json.Marshal(AgentsControlResponse{
-			ProjectID:   s.Project.Project.ProjectId,
-			ProjectName: s.Project.Project.Name,
-			Agents:      s.Project.Project.Agents,
-		})
+		agents, err := s.getAgents(r.Context(), s.Project.Project)
 		if err != nil {
 			s.logger.Error("failed to marshal agents control response: %s", err)
 			w.WriteHeader(http.StatusInternalServerError)
 			return
 		}
 		w.Header().Set("Content-Type", "application/json")
-		w.Write(buf)
+		io.WriteString(w, cstr.JSONStringify(agents))
 		return
 	case "/_control":
 		sendCORSHeaders(w.Header())
@@ -247,7 +271,16 @@ func (s *Server) handleStream(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
 		rc := http.NewResponseController(w)
 		rc.Flush()
+		s.HealthCheck(fmt.Sprintf("http://127.0.0.1:%d", s.port)) // make sure the server is running
 		w.Write([]byte("event: start\ndata: connected\n\n"))
+		agents, err := s.getAgents(r.Context(), s.Project.Project)
+		if err != nil {
+			s.logger.Error("failed to marshal agents control response: %s", err)
+			w.Write([]byte(fmt.Sprintf("event: error\ndata: %q\n\n", err.Error())))
+			rc.Flush()
+			return
+		}
+		w.Write([]byte(fmt.Sprintf("event: agents\ndata: %s\n\n", cstr.JSONStringify(agents))))
 		rc.Flush()
 		select {
 		case <-s.ctx.Done():
@@ -258,12 +291,6 @@ func (s *Server) handleStream(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if r.Method != "POST" {
-		sendCORSHeaders(w.Header())
-		w.WriteHeader(http.StatusMethodNotAllowed)
-		return
-	}
-
 	agentId := r.URL.Path[1:]
 	var found bool
 	for _, agent := range s.Project.Project.Agents {
@@ -281,6 +308,11 @@ func (s *Server) handleStream(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if r.Method == "GET" {
+		message.CustomErrorResponse(w, "Agents, Not Humans, Live Here", "Hi! I'm an Agentuity Agent running in development mode.", "", http.StatusOK)
+		return
+	}
+
 	sctx, logger, span := telemetry.StartSpan(r.Context(), s.logger, s.tracer, "TriggerRun",
 		trace.WithAttributes(
 			attribute.Bool("@agentuity/devmode", true),
@@ -373,6 +405,55 @@ func (s *Server) AgentURL(agentId string) string {
 	return fmt.Sprintf("http://127.0.0.1:%d/%s", s.port, agentId)
 }
 
+func isConnectionErrorRetryable(err error) bool {
+	if strings.Contains(err.Error(), "connection refused") {
+		return true
+	}
+	if strings.Contains(err.Error(), "connection reset by peer") {
+		return true
+	}
+	if strings.Contains(err.Error(), "No connection could be made because the target machine actively refused it") { // windows
+		return true
+	}
+	return false
+}
+
+type Welcome struct {
+	Message string `json:"welcome"`
+	Prompts []struct {
+		Data        string `json:"data"`
+		ContentType string `json:"contentType"`
+	} `json:"prompts,omitempty"`
+}
+
+func (s *Server) getWelcome(ctx context.Context, port int) (map[string]Welcome, error) {
+	url := fmt.Sprintf("http://127.0.0.1:%d/welcome", port)
+	for i := 0; i < 5; i++ {
+		req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+		if err != nil {
+			return nil, err
+		}
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			if isConnectionErrorRetryable(err) {
+				time.Sleep(time.Millisecond * time.Duration(100*i+1))
+				continue
+			}
+			return nil, err
+		}
+		defer resp.Body.Close()
+		if resp.StatusCode == 404 {
+			return nil, nil // this is ok, just means no agents have inspect
+		}
+		res := make(map[string]Welcome)
+		if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+			return nil, err
+		}
+		return res, nil
+	}
+	return nil, fmt.Errorf("failed to inspect agents after 5 attempts")
+}
+
 func (s *Server) HealthCheck(devModeUrl string) error {
 	started := time.Now()
 	var i int