Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
node: rename debug observed addresses to announced addresses
Joyboyc0e279793987
diff --git a/AGENTS.md b/AGENTS.mdindex 35169d1f..c0db8088 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -5,7 +5,7 @@ You are an expert software engineering assistant helping to develop, maintain, a## 1. Architecture & Component Independence* **Decoupled Architecture:** The `sam-control-plane`, `sam-router` and `sam-node` components are strictly independent. They must not share internal state or tightly couple their logic.* **API Communication:** All data communication between `sam-control-plane`, `sam-router` and `sam-node` must happen exclusively via the common API defined in `api/sam.proto`.-* **One schema, two encodings:** every request and response on any SAM-defined surface is a message in `api/sam.proto`. The *mesh protocol* — anything a mesh component speaks (node, router, the SDKs under `sdk/`): enrollment, refresh, keys, leases, auth streams, policy sync, token exchange (`/token/exchange`), and outbound border JWT minting (`/sts/token`) — is binary protobuf (`application/x-protobuf`). The *operator plane* — what humans, the web console and admin CLIs call (`/admin/*`, `/users/*`, `POST /policies`) — is protojson of the same messages, with `UseProtoNames` and unknown fields rejected. Never define a wire shape on a SAM-defined surface as a Go struct with `json` tags, an anonymous struct or `map[string]any`, and never serialize an `internal/storage` (or any other internal) type onto either surface. The sole exceptions are external standard protocols for unmodified third-party clients and cloud federation: OAuth 2.1 / RFC 8693 / RFC 7009 / RFC 9728 (`POST /oauth/token`, `POST /oauth/revoke`, `/oauth/authorize`, `/.well-known/*`, `/jwks`), Envoy `ext_authz` / `ext_proc`, MCP JSON-RPC (`/mcp`), OpenAI `/v1/*`, and A2A `/.well-known/agent-card.json`. Clients in `cmd/`, `internal/console` and `sdk/` import `api/` or its generated bindings only.+* **One schema, two encodings:** every request and response on any SAM-defined surface is a message in `api/sam.proto`. The *mesh protocol* — anything a mesh component speaks (node, router, the SDKs under `sdk/`): enrollment, refresh, keys, leases, auth streams, policy sync, token exchange (`/token/exchange`), and outbound border JWT minting (`/sts/token`) — is binary protobuf (`application/x-protobuf`). The *operator plane* — what humans, the web console and admin CLIs call (`/admin/*`, `/users/*`, `POST /policies`) — is protojson of the same messages, with `UseProtoNames` and unknown fields rejected. Never define a wire shape on a SAM-defined surface as a Go struct with `json` tags, an anonymous struct or `map[string]any`, and never serialize an `internal/storage` (or any other internal) type onto either surface. The sole exceptions are external standard protocols for unmodified third-party clients and cloud federation: OAuth 2.1 / RFC 8693 / RFC 7009 / RFC 9728 (`POST /oauth/token`, `POST /oauth/revoke`, `/oauth/authorize`, `/.well-known/*`, `/jwks`), Envoy `ext_authz` / `ext_proc`, MCP JSON-RPC (`/mcp`), OpenAI `/v1/*`, and A2A `/.well-known/agent-card.json`. Clients in `cmd/`, `internal/console` and `sdk/` import `api/` or its generated bindings only. The node's `/debug/*` endpoints are exempt: unversioned diagnostics for humans, printed as-is by `sam-node debug` and parsed by no client, so they stay unexported Go structs.* **Instants are `google.protobuf.Timestamp`, named `*_time`** (`expire_time`, `sign_time`, `event_time`), never `int64` seconds or milliseconds. `Timestamp` has fixed units, an explicit unset, renders as RFC 3339 in protojson (an `int64` renders as a quoted decimal string), and has a first-class conversion in Go, JavaScript, Python and Dart. A receiver treats an unset instant as invalid, never as the epoch. The one exception is a proof-of-possession value: it is the number that appears in the signed text (`sam:<endpoint>:<peer_id>:<n>`), so it stays an `int64` named `challenge_unix_ms`, the unit in the name. What a member persists between runs is also a message here (`MemberCredential`), so a state directory written by one implementation loads in another.* **Datalog text is the policy contract:** the control plane renders the mesh policy as Datalog rules (`PolicyConfigGetResponse.datalog_rules`); every member, in any language, adds that text to its authorizer and none derives rules from roles and bindings itself. Datalog must stay in the form every Biscuit implementation parses: a predicate carries at least one term (presence-only facts are `name(true)`, see `api.MarkerFact`).* **Secrets never travel as flag values:** binaries read credentials from a file (`--*-path`) or the environment, never from a command-line argument that would sit in `ps` output and shell history. Banners and logs name the source of an operator-supplied secret instead of echoing it.diff --git a/agents/skills/sam-mesh/SKILL.md b/agents/skills/sam-mesh/SKILL.mdindex 7f4a7a8f..19d3424f 100644--- a/agents/skills/sam-mesh/SKILL.md+++ b/agents/skills/sam-mesh/SKILL.md@@ -119,7 +119,7 @@ endpoint over the node's Unix socket — no token involved:```bashsam-node debug mesh-info # connected peers, DHT size, router peer IDsam-node debug connectivity [peer-id] # ping the SAM router, or a specific peer-sam-node debug network-info # listen and observed addresses+sam-node debug network-info # listen and announced addressessam-node debug token-info # local auth token expiration and statussam-node debug logs # recent log linessam-node debug connect-peer <multiaddr> # manually dial a peerdiff --git a/cmd/sam-node/debug.go b/cmd/sam-node/debug.goindex a4272080..d801f386 100644--- a/cmd/sam-node/debug.go+++ b/cmd/sam-node/debug.go@@ -41,7 +41,7 @@ func newDebugCmd() *cobra.Command {debugCmd.AddCommand(newDebugGetCmd("mesh-info", "Show connected peers, DHT size, and the router peer ID", "/debug/mesh-info"),- newDebugGetCmd("network-info", "Show local network interfaces and listener addresses", "/debug/network-info"),+ newDebugGetCmd("network-info", "Show listener and announced addresses", "/debug/network-info"),newDebugGetCmd("token-info", "Show the local auth token's expiration and status", "/debug/token-info"),newDebugGetCmd("logs", "Show the last few lines of the node's log output", "/debug/logs"),)diff --git a/internal/node/debug_handlers.go b/internal/node/debug_handlers.goindex ff0cf323..ffa8a67c 100644--- a/internal/node/debug_handlers.go+++ b/internal/node/debug_handlers.go@@ -139,8 +139,8 @@ type tokenInfoResponse struct {}type networkInfoResponse struct {- ListenAddresses []string `json:"listen_addresses"`- ObservedAddresses []string `json:"observed_addresses"`+ ListenAddresses []string `json:"listen_addresses"`+ AnnouncedAddresses []string `json:"announced_addresses"`}type logsResponse struct {@@ -238,14 +238,14 @@ func (n *SamNode) networkInfo() networkInfoResponse {listenAddrs = append(listenAddrs, a.String())}- observedAddrs := []string{}+ announcedAddrs := []string{}for _, a := range n.Host.Addrs() {- observedAddrs = append(observedAddrs, a.String())+ announcedAddrs = append(announcedAddrs, a.String())}return networkInfoResponse{- ListenAddresses: listenAddrs,- ObservedAddresses: observedAddrs,+ ListenAddresses: listenAddrs,+ AnnouncedAddresses: announcedAddrs,}}diff --git a/internal/node/mcp_handlers_additional_test.go b/internal/node/mcp_handlers_additional_test.goindex 423ecc67..dc3fc751 100644--- a/internal/node/mcp_handlers_additional_test.go+++ b/internal/node/mcp_handlers_additional_test.go@@ -145,6 +145,9 @@ func TestNetworkInfo(t *testing.T) {if len(info.ListenAddresses) == 0 {t.Fatalf("expected listen addresses, got %+v", info)}+ if len(info.AnnouncedAddresses) == 0 {+ t.Fatalf("expected announced addresses, got %+v", info)+ }}// TestDebugHandlerHTTP exercises the /debug mux itself: routing, method@@ -173,6 +176,18 @@ func TestDebugHandlerHTTP(t *testing.T) {}}+ networkInfo := get("/debug/network-info")+ if !strings.Contains(networkInfo.Body.String(), `"announced_addresses"`) {+ t.Fatalf("network info response does not contain announced_addresses: %s", networkInfo.Body.String())+ }+ var info networkInfoResponse+ if err := json.Unmarshal(networkInfo.Body.Bytes(), &info); err != nil {+ t.Fatalf("decode network info response: %v", err)+ }+ if len(info.AnnouncedAddresses) == 0 {+ t.Fatalf("network info response has no announced_addresses: %s", networkInfo.Body.String())+ }+rec := get("/debug/connect-peer")if rec.Code != http.StatusMethodNotAllowed {t.Errorf("GET /debug/connect-peer: got %d, want 405", rec.Code)diff --git a/tests/integration/debug_endpoints_test.go b/tests/integration/debug_endpoints_test.goindex 40d7587c..cbbd3318 100644--- a/tests/integration/debug_endpoints_test.go+++ b/tests/integration/debug_endpoints_test.go@@ -167,6 +167,10 @@ roles: []t.Run("network-info", func(t *testing.T) {resp := debugGet(t, actualApiAddrA, "/debug/network-info")+ if !strings.Contains(resp, `"announced_addresses"`) {+ t.Fatalf("network info response does not contain announced_addresses: %s", resp)+ }+var info map[string]anyif err := json.Unmarshal([]byte(resp), &info); err != nil {t.Fatalf("failed to unmarshal JSON: %v", err)@@ -174,6 +178,9 @@ roles: []if addresses, ok := info["listen_addresses"].([]any); !ok || len(addresses) == 0 {t.Errorf("expected listen_addresses array, got %v", info)}+ if addresses, ok := info["announced_addresses"].([]any); !ok || len(addresses) == 0 {+ t.Errorf("expected announced_addresses array, got %v", info)+ }})t.Run("connectivity", func(t *testing.T) {