sambox: an agent serves only itself, over A2A, contracted statically

Runtime service declaration is gone from the sandbox boundary. The bundle
now contracts at most one thing - the agent's own a2a service name and
the sandbox port it must bind (like $PORT on a serverless runtime) - and
the gateway routes it from startup, never talking to the node. The
operator declares the a2a:// service in the node's configuration with the
gateway's stable --ingress-listen address as its backend.

Everything that made runtime declaration feel necessary lives at its
proper layer instead: capabilities and dynamic behaviour are the agent
card and A2A traffic inside the route; readiness is the node's new
card-fetch probe (an A2A agent is up exactly when it serves its card), so
a declared-but-unbound sandbox stays out of discovery and a moved agent
re-points via probe-gated advertisement rather than re-registration.
Tools (mcp://) and models (inference://) remain operator node services,
never agent ingress.

The CUJ now runs the stock a2a-go SDK on both ends: an unmodified agent
server in the sandbox and an unmodified client bootstrapping from the
mesh-regenerated card.

Author: aojea

cmd/sam-box/main.go

@@ -51,6 +51,7 @@ func main() {
 		logLevel      string
 
 		agentIngressSocket string
+		ingressListen      string
 	)
 
 	rootCmd := &cobra.Command{
@@ -78,12 +79,12 @@ func main() {
 			if err := verifyBundleCredential(cmd.Context(), bundlePath, issuer, audience, insecure); err != nil {
 				return err
 			}
-			ingress, err := resolveIngress(bundlePath, sidecarSocket, agentIngressSocket)
+			ingress, err := resolveIngress(bundlePath, ingressListen, agentIngressSocket)
 			if err != nil {
 				return err
 			}
 			if ingress != nil {
-				defer ingress.Close(context.WithoutCancel(cmd.Context()))
+				defer ingress.Close()
 			}
 
 			listener, err := sambox.ListenSandboxSocket(sandboxSocket)
@@ -107,7 +108,6 @@ func main() {
 					Router:        &sambox.Router{Egress: egress},
 					SidecarSocket: sidecarSocket,
 					AgentID:       agentID,
-					Ingress:       ingress,
 				},
 			}
 
@@ -136,6 +136,7 @@ func main() {
 	runCmd.Flags().BoolVar(&insecure, "insecure-unverified-bundle", false, "Trust the bundle's declared identity without a credential to back it, letting whoever can write the file decide which agent this sandbox is")
 	runCmd.Flags().StringVar(&metricsAddr, "metrics-addr", "", "Serve unauthenticated Prometheus metrics on this address, e.g. 127.0.0.1:9600; off by default")
 	runCmd.Flags().StringVar(&agentIngressSocket, "agent-ingress-socket", "", "Path to the sandbox's reverse channel, served by nano-init --ingress-socket; required to reach an agent that serves the mesh, because an isolated sandbox cannot be dialled")
+	runCmd.Flags().StringVar(&ingressListen, "ingress-listen", "127.0.0.1:7080", "Stable address the gateway's mesh-facing ingress listens on; the node's configuration declares services with this address as their backend")
 	runCmd.Flags().StringVar(&logLevel, "log-level", "info", "Log level (debug, info, warn, error)")
 	for _, required := range []string{"socket", "sidecar-socket"} {
 		if err := runCmd.MarkFlagRequired(required); err != nil {
@@ -222,31 +223,39 @@ func verifyBundleCredential(ctx context.Context, bundlePath, issuer, audience st
 
 // resolveIngress prepares what the agent is permitted to serve. Nil means
 // nothing, which is the case for a sandbox that only calls out.
-func resolveIngress(bundlePath, sidecarSocket, agentIngressSocket string) (*sambox.IngressManager, error) {
+func resolveIngress(bundlePath, ingressListen, agentIngressSocket string) (*sambox.IngressManager, error) {
 	if bundlePath == "" {
 		return nil, nil
 	}
 	bundle, err := sambox.LoadAgentBundle(bundlePath)
 	if err != nil {
 		return nil, err
 	}
-	if len(bundle.Ingress) == 0 {
+	if bundle.Serves == nil {
 		return nil, nil
 	}
 	if agentIngressSocket == "" {
 		// Refused rather than degraded. Without a channel into the sandbox the
 		// only address left is one in this process's network namespace, which
 		// is the pod's: the node's API and every sidecar are on that loopback,
 		// and the port would be the agent's to choose.
-		return nil, fmt.Errorf("agent %s may serve %d mesh service(s), but --agent-ingress-socket is not set. "+
+		return nil, fmt.Errorf("agent %s serves a2a://%s, but --agent-ingress-socket is not set. "+
 			"Point it at the path nano-init --ingress-socket serves; without it there is no way into the "+
 			"sandbox, and delivering to this process's own network namespace would reach the gateway's "+
-			"neighbours instead of the agent", bundle.Agent.ID, len(bundle.Ingress))
-	}
-	logger.Infof("Agent %s may serve %d mesh service(s) once it announces them", bundle.Agent.ID, len(bundle.Ingress))
-	return &sambox.IngressManager{
-		SidecarSocket: sidecarSocket,
-		Allowed:       bundle.Ingress,
-		AgentSocket:   agentIngressSocket,
-	}, nil
+			"neighbours instead of the agent", bundle.Agent.ID, bundle.Serves.Name)
+	}
+	manager := &sambox.IngressManager{
+		ListenAddr:  ingressListen,
+		Serves:      *bundle.Serves,
+		AgentSocket: agentIngressSocket,
+	}
+	// The routes are the bundle's contract and exist from startup; the node's
+	// config declares services backed by this address, and its backend probe
+	// fails until the agent actually binds its contracted port.
+	addr, err := manager.Start()
+	if err != nil {
+		return nil, fmt.Errorf("serving ingress on %s: %w", ingressListen, err)
+	}
+	logger.Infof("Agent %s serves a2a://%s; ingress at http://%s", bundle.Agent.ID, bundle.Serves.Name, addr)
+	return manager, nil
 }

internal/node/a2a_service.go

@@ -56,6 +56,36 @@ func (s *A2AService) Init(ctx context.Context) error {
 	return nil
 }
 
+// Probe asks the backend for its agent card, which is the protocol's own
+// definition of ready: an A2A agent is up exactly when it serves its card.
+// Gating advertisement on it lets a service be declared before its agent is
+// (a sandbox that has not bound its port yet probes as down and stays out of
+// discovery). Deliberately not cached, like the MCP probe.
+func (s *A2AService) Probe(ctx context.Context) error {
+	target, ok := s.backend.(*api.RegisterServiceRequest_TargetUrl)
+	if !ok {
+		return fmt.Errorf("a2a service %q has no URL backend to probe", s.info.GetName())
+	}
+	cardURL := strings.TrimSuffix(target.TargetUrl, "/") + "/.well-known/agent-card.json"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, cardURL, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("fetch agent card of %q: %w", s.info.GetName(), err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("agent card of %q: %s", s.info.GetName(), resp.Status)
+	}
+	var card map[string]any
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&card); err != nil {
+		return fmt.Errorf("agent card of %q is not JSON: %w", s.info.GetName(), err)
+	}
+	return nil
+}
+
 // a2aEgressGate runs the caller-side A2A checks on a raw egress request:
 // the fail-closed labels gate. On refusal it writes the HTTP error itself
 // and returns ok=false.

internal/node/a2a_service_test.go

@@ -65,6 +65,57 @@ func TestNewServiceFromRequestA2A(t *testing.T) {
 	}
 }
 
+// TestA2AServiceProbe pins advertisement gating on the agent card: an a2a
+// service may be declared before its agent is up (a sandbox that has not
+// bound its port), and must probe as down until the card is served.
+func TestA2AServiceProbe(t *testing.T) {
+	newSvc := func(target string) *A2AService {
+		return &A2AService{baseService: baseService{
+			info:    &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_A2A, Name: "agent"},
+			backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: target},
+		}}
+	}
+
+	t.Run("card served means ready", func(t *testing.T) {
+		backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.URL.Path != "/.well-known/agent-card.json" {
+				http.NotFound(w, r)
+				return
+			}
+			_, _ = w.Write([]byte(`{"name":"agent","version":"1.0.0"}`))
+		}))
+		defer backend.Close()
+		if err := newSvc(backend.URL).Probe(context.Background()); err != nil {
+			t.Fatalf("Probe with a served card: %v", err)
+		}
+	})
+
+	t.Run("no card means not ready", func(t *testing.T) {
+		backend := httptest.NewServer(http.NotFoundHandler())
+		defer backend.Close()
+		if err := newSvc(backend.URL).Probe(context.Background()); err == nil {
+			t.Fatal("Probe must fail while the card is not served")
+		}
+	})
+
+	t.Run("dead backend means not ready", func(t *testing.T) {
+		// A declared sandbox service whose agent never bound its port.
+		if err := newSvc("http://127.0.0.1:1").Probe(context.Background()); err == nil {
+			t.Fatal("Probe must fail when nothing listens")
+		}
+	})
+
+	t.Run("non-json card means not ready", func(t *testing.T) {
+		backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			_, _ = w.Write([]byte("<html>login page</html>"))
+		}))
+		defer backend.Close()
+		if err := newSvc(backend.URL).Probe(context.Background()); err == nil {
+			t.Fatal("Probe must fail on a non-JSON card")
+		}
+	})
+}
+
 func TestA2AEgressHookNonA2APassthrough(t *testing.T) {
 	rec := httptest.NewRecorder()
 	req := httptest.NewRequest("GET", "/sam/12D3KooWpeer/mcp/svc/foo", nil)

internal/sambox/bundle.go

@@ -39,22 +39,26 @@ type AgentBundle struct {
 	Agent   AgentIdentity `yaml:"agent"`
 	Egress  BundleEgress  `yaml:"egress"`
 
-	// Ingress is what this agent is permitted to serve, not what it is
-	// currently serving. The agent says when it is ready, and on which port,
-	// through the gateway's ingress endpoint; the platform decides only which
-	// names it may claim.
-	Ingress []BundleIngress `yaml:"ingress"`
+	// Serves is the one mesh service this agent provides: itself, as an A2A
+	// agent. The name is the platform's grant and the port is its contract
+	// with the agent (like $PORT on a serverless runtime); the agent binds it
+	// when ready, and everything else about serving -- capabilities, skills,
+	// negotiation -- lives on the agent's own card, inside the A2A protocol.
+	// Tools (mcp://) and models (inference://) are operator workloads declared
+	// in a node's configuration, never agent ingress.
+	Serves *BundleServes `yaml:"serves,omitempty"`
 
 	// egress is the compiled form of Egress.Allow, built during loading so a
 	// malformed allowlist fails at startup rather than on an agent's first
 	// request.
 	egress *EgressPolicy
 }
 
-// BundleIngress is one mesh service the agent may advertise.
-type BundleIngress struct {
+// BundleServes contracts the agent's own a2a service: its mesh name and the
+// sandbox port it must bind.
+type BundleServes struct {
 	Name string `yaml:"name"`
-	Type string `yaml:"type"`
+	Port int    `yaml:"port"`
 }
 
 // AgentIdentity names the principal the gateway asserts for this sandbox.
@@ -106,12 +110,12 @@ func LoadAgentBundle(path string) (*AgentBundle, error) {
 	}
 	bundle.egress = policy
 
-	for i, ingress := range bundle.Ingress {
-		if _, err := api.ParseServiceType(ingress.Type); err != nil {
-			return nil, fmt.Errorf("agent bundle %s: ingress %d: %w", path, i, err)
+	if bundle.Serves != nil {
+		if err := api.ValidateServiceFormat("a2a://" + bundle.Serves.Name); err != nil {
+			return nil, fmt.Errorf("agent bundle %s: serves: %w", path, err)
 		}
-		if err := api.ValidateServiceFormat(ingress.Type + "://" + ingress.Name); err != nil {
-			return nil, fmt.Errorf("agent bundle %s: ingress %d: %w", path, i, err)
+		if bundle.Serves.Port < 1 || bundle.Serves.Port > 65535 {
+			return nil, fmt.Errorf("agent bundle %s: serves: port %d is not a port", path, bundle.Serves.Port)
 		}
 	}
 

internal/sambox/dial.go

@@ -46,11 +46,6 @@ type AgentDialer struct {
 	// unidentified, and mesh policy sees only the node it came through.
 	AgentID string
 
-	// Ingress serves what the agent is permitted to advertise. Nil means the
-	// agent may serve nothing, which is the case for a sandbox that only calls
-	// out.
-	Ingress *IngressManager
-
 	// DialContext opens external destinations. Nil uses a plain net.Dialer;
 	// tests and future egress interception replace it.
 	DialContext func(ctx context.Context, network, address string) (net.Conn, error)

internal/sambox/entrypoint.go

@@ -43,11 +43,9 @@ import (
 // Discovery is not on the list even though agents need it: it is already
 // available through MCP as find_remote_tools and discover_remote_services, so
 // exposing /sam/service/discover as well would widen the surface without adding
-// a capability. Registration is not on the list at all — an agent that could
-// register would advertise itself into the mesh under the node's identity, and
-// choose the target_url the mesh then routes to. What an agent may serve is
-// declared by the platform in its bundle, and announced through the gateway's
-// own /ingress endpoint, which never reaches the node.
+// a capability. Serving is not on the list at all — what an agent serves is
+// declared by the platform in its bundle and by the operator in the node's
+// configuration, and the agent's only part is binding its contracted port.
 func agentMayReach(path string) bool {
 	switch path {
 	case "/v1/models", "/v1/chat/completions", "/v1/completions":
@@ -56,9 +54,6 @@ func agentMayReach(path string) bool {
 	return path == "/mcp" || strings.HasPrefix(path, "/mcp/")
 }
 
-// ingressPath is served by the gateway itself rather than proxied.
-const ingressPath = "/ingress"
-
 // dialMeshEntrypoint returns a connection serving the agent-facing surface.
 func (d *AgentDialer) dialMeshEntrypoint() (net.Conn, error) {
 	if d.SidecarSocket == "" {
@@ -78,22 +73,9 @@ func (d *AgentDialer) entrypointHandler() http.Handler {
 		Transport: d.sidecarTransport(),
 	}
 
-	var ingress http.Handler
-	if d.Ingress != nil {
-		ingress = d.Ingress.Handler()
-	}
-
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path == ingressPath {
-			if ingress == nil {
-				http.Error(w, "this agent was granted nothing to serve", http.StatusForbidden)
-				return
-			}
-			ingress.ServeHTTP(w, r)
-			return
-		}
 		if !agentMayReach(r.URL.Path) {
-			http.Error(w, "the mesh entrypoint serves /v1, /mcp and /ingress only", http.StatusForbidden)
+			http.Error(w, "the mesh entrypoint serves /v1 and /mcp only", http.StatusForbidden)
 			return
 		}
 		proxy.ServeHTTP(w, r)