Add macOS companion node status and system.nodes APIs

src/gateway/handlers/system.ts

@@ -2,7 +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';
+import type { NodeLocation, NodeStatus } from './node.js';
 
 /** Per-session token usage report returned by system.tokenUsage. */
 export interface TokenUsageEntry {
@@ -29,6 +29,18 @@ export interface NodeLocationEntry {
   location: NodeLocation;
 }
 
+export interface NodeEntry {
+  connectionId: string;
+  nodeId: string;
+  role: string;
+  identity?: string;
+  protocolVersion: number;
+  capabilities: string[];
+  registeredAt: number;
+  location?: NodeLocation;
+  status?: NodeStatus;
+}
+
 export interface SystemHandlerDeps {
   startTime: number;
   version: string;
@@ -53,6 +65,8 @@ export interface SystemHandlerDeps {
   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[];
+  /** Optional callback to retrieve registered node connection snapshots. */
+  getNodes?: (opts?: { role?: string; platform?: string; limit?: number }) => NodeEntry[];
 }
 
 export function createSystemHandlers(deps: SystemHandlerDeps) {
@@ -142,6 +156,25 @@ export function createSystemHandlers(deps: SystemHandlerDeps) {
       });
     },
 
+    'system.nodes': async (request: GatewayRequest): Promise<OutboundMessage> => {
+      if (!deps.getNodes) {
+        return makeResponse(request.id, { nodes: [], summary: { total: 0 } });
+      }
+
+      const params = request.params as { role?: string; platform?: string; limit?: number } | undefined;
+      const nodes = deps.getNodes({
+        role: params?.role,
+        platform: params?.platform,
+        limit: params?.limit,
+      });
+      return makeResponse(request.id, {
+        nodes,
+        summary: {
+          total: nodes.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 };