Move network diagnostics from MCP tools to /debug REST endpoints + sam-node debug CLI

[kaisoz]

Fixes #318.

The node's MCP server exposed 16 tools to every connected agent, five of which are operator diagnostics, not mesh usage. This PR removes those five from the agent-facing tool list and re-exposes them as REST endpoints under /debug on the sidecar mux (following the /debug naming discussed in the issue), plus a sam-node debug command group that reaches them over the node's Unix socket.

Endpoints

Endpoint	Replaces MCP tool	CLI subcommand	What it touches	Network I/O	Behavior while disconnected from the mesh
GET /debug/mesh-info	(none — get_mesh_info stays an MCP tool; this is the operator's view of the same data)	sam-node debug mesh-info	Host.Network().Peers() (in-memory connection table), DHT.RoutingTable().Size(), RouterPeerID, BoundSocketPath	none	Works; honestly reports 0 connected peers
GET /debug/connectivity[?peer_id=…]	check_connectivity	sam-node debug connectivity [peer-id]	Dials the SAM router (or the given peer) via Host.Connect and measures latency	one bounded dial	Works; this is exactly the state it exists to diagnose (router_error_msg, ping_latency_ms)
GET /debug/network-info	get_network_info	sam-node debug network-info	Host.Network().ListenAddresses(), Host.Addrs()	none	Works; purely local address lists
GET /debug/token-info	get_token_info	sam-node debug token-info	Store.LoadIdentity() / LoadIdentityExpiration() (local store)	none	Works; answers "am I disconnected because my token expired?"
GET /debug/logs	get_recent_logs	sam-node debug logs	In-process log ring buffer	none	Works; purely local
POST /debug/connect-peer	connect_peer	sam-node debug connect-peer <multiaddr>	Host.Connect to the given multiaddr; revoked-peer and banned-peer checks kept from the tool handler	one outbound dial	Works; it is the manual recovery action for a node that lost its router — a direct dial to an explicit address needs no router

Auth and gating

• All six endpoints sit behind withAuth(token, allowAuthorizationFallback=true, …)
• They deliberately do not get withMeshConnection: four endpoints are pure local reads, and the two that dial take a concrete address and do one bounded attempt whose error is the diagnostic output. Gating them 503s exactly when an operator needs them.
• Previously the five tools were behind withMeshConnection only incidentally, because all MCP traffic shares the "/" route on the sidecar mux — diagnostics were unusable on a disconnected node. Moving them to /debug makes that gating decision explicit.

CLI

sam-node debug <subcommand> talks HTTP over the Unix socket (--socket-path, defaulting to <data-dir>/sam.sock like run), so the socket's 0600 permissions are the credential and no token appears anywhere. Output is the endpoint's raw JSON, so it composes with jq. Root help grows by one entry regardless of how many diagnostics are added later.

$ sam-node debug connectivity
{"connected_peers":3,"router_error":false,"router_latency_ms":2,"total_known_peers":14}
$ sam-node debug connect-peer /ip4/10.0.0.5/tcp/5002/p2p/12D3Koo...
{"status":"connected"}

[gemini-code-assist]

Code Review

This pull request migrates operator diagnostics and debug utilities (such as mesh info, connectivity stats, token info, network info, and peer connection) from MCP tools to dedicated HTTP endpoints served over a Unix socket. The corresponding MCP tools have been removed, and integration tests have been updated to use the new REST endpoints. The review feedback highlights several potential nil pointer dereference panics across the new debug handler methods (meshInfo, connectivityStats, tokenInfo, networkInfo, and connectPeer) where n.Host, n.DHT, or n.Store are accessed without prior nil checks.

[aojea]

/gemini review

[gemini-code-assist]

Code Review

This pull request moves operator diagnostics (such as mesh-info, connectivity, network-info, token-info, and logs) from MCP tools to dedicated /debug HTTP endpoints served over a Unix socket, making them invisible to agents and accessible even when the mesh is unreachable. Feedback focuses on adding defensive checks across the new debug handler methods to prevent potential nil pointer dereferences on uninitialized fields (such as Host, DHT, or Store). Additionally, it is recommended to enforce timeouts on connection contexts to prevent indefinite blocking and to validate that the socket path is not empty before dialing.

[aojea]

it needs rebase

[kaisoz]

/gemini review

[gemini-code-assist]

Code Review

This pull request moves operator diagnostics (such as logs, connectivity, network/token info, and peer connections) out of the Model Context Protocol (MCP) tools list and into dedicated /debug/ REST endpoints. This prevents agents from seeing these diagnostic tools in their tool list. A new sam-node debug CLI command has been introduced to interact with these endpoints, and tests and documentation have been updated accordingly. Feedback includes pre-allocating the connectedPeers slice in debug_handlers.go to avoid serializing to null when empty, and using a lightweight curlimages/curl container instead of python:3.12 in E2E tests to improve execution speed.

[aojea]

now A2A and we are moving to beta , go go go 💪