Add node location access RPCs and operator visibility

src/gateway/handlers/system.ts

@@ -2,6 +2,7 @@ import type { GatewayRequest, OutboundMessage } from '../protocol.js';
 import { makeResponse, makeError, ErrorCode } from '../protocol.js';
 import type { MetricsSnapshot, EventEntry, ActiveRequestInfo } from '../metrics.js';
 import type { ServiceInfo } from './services.js';
+import type { NodeLocation } from './node.js';
 
 /** Per-session token usage report returned by system.tokenUsage. */
 export interface TokenUsageEntry {
@@ -21,6 +22,13 @@ export interface PresenceEntry {
   status: 'online' | 'offline';
 }
 
+export interface NodeLocationEntry {
+  nodeId: string;
+  role: string;
+  connectionId: string;
+  location: NodeLocation;
+}
+
 export interface SystemHandlerDeps {
   startTime: number;
   version: string;
@@ -43,6 +51,8 @@ export interface SystemHandlerDeps {
   getServices?: () => ServiceInfo[];
   /** Optional callback to retrieve tracked sender presence. */
   getPresence?: (opts?: { channel?: string; status?: 'online' | 'offline'; limit?: number }) => PresenceEntry[];
+  /** Optional callback to retrieve latest node location data. */
+  getNodeLocations?: (opts?: { role?: string; nodeId?: string; limit?: number }) => NodeLocationEntry[];
 }
 
 export function createSystemHandlers(deps: SystemHandlerDeps) {
@@ -113,6 +123,25 @@ export function createSystemHandlers(deps: SystemHandlerDeps) {
       });
     },
 
+    'system.location': async (request: GatewayRequest): Promise<OutboundMessage> => {
+      if (!deps.getNodeLocations) {
+        return makeResponse(request.id, { locations: [], summary: { total: 0 } });
+      }
+
+      const params = request.params as { role?: string; nodeId?: string; limit?: number } | undefined;
+      const locations = deps.getNodeLocations({
+        role: params?.role,
+        nodeId: params?.nodeId,
+        limit: params?.limit,
+      });
+      return makeResponse(request.id, {
+        locations,
+        summary: {
+          total: locations.length,
+        },
+      });
+    },
+
     'system.usage': async (request: GatewayRequest): Promise<OutboundMessage> => {
       const uptime = Math.floor((Date.now() - deps.startTime) / 1000);
       const usage = deps.getUsage?.() ?? { totalSessions: 0, activeConnections: 0 };