Skip to content

Agent Mesh

node: rename debug observed addresses to announced addresses

Joyboyc0e279793987
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index 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:
```bash
sam-node debug mesh-info # connected peers, DHT size, router peer ID
sam-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 addresses
sam-node debug token-info # local auth token expiration and status
sam-node debug logs # recent log lines
sam-node debug connect-peer <multiaddr> # manually dial a peer
diff --git a/cmd/sam-node/debug.go b/cmd/sam-node/debug.go
index 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.go
index 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.go
index 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.go
index 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]any
if 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) {