feat(gateway): add system.sessionAnalytics usage snapshot RPC

src/gateway/handlers/system.ts

@@ -3,6 +3,7 @@ import { makeResponse, makeError, ErrorCode } from '../protocol.js';
 import type { MetricsSnapshot, EventEntry, ActiveRequestInfo } from '../metrics.js';
 import type { ServiceInfo } from './services.js';
 import type { NodeLocation, NodeStatus, NodePushToken } from './node.js';
+import type { SessionAnalyticsSnapshot } from '../../session/index.js';
 
 /** Per-session token usage report returned by system.tokenUsage. */
 export interface TokenUsageEntry {
@@ -64,6 +65,8 @@ export interface SystemHandlerDeps {
   getTokenUsage?: () => TokenUsageEntry[];
   /** Optional callback to retrieve aggregated metrics snapshot. */
   getMetrics?: () => MetricsSnapshot;
+  /** Optional callback to retrieve session analytics. */
+  getSessionAnalytics?: (opts?: { days?: number; topLimit?: number }) => SessionAnalyticsSnapshot;
   /** Optional callback to retrieve recent events. */
   getEvents?: (opts?: { level?: string; limit?: number }) => EventEntry[];
   /** Optional callback to retrieve active requests. */
@@ -206,6 +209,24 @@ export function createSystemHandlers(deps: SystemHandlerDeps) {
       return makeResponse(request.id, deps.getMetrics());
     },
 
+    'system.sessionAnalytics': async (request: GatewayRequest): Promise<OutboundMessage> => {
+      if (!deps.getSessionAnalytics) {
+        return makeResponse(request.id, {
+          daily: [],
+          topSessions: [],
+          averageMessagesPerSession: 0,
+          totalSessions: 0,
+          totalMessages: 0,
+        });
+      }
+      const params = request.params as { days?: number; topLimit?: number } | undefined;
+      const snapshot = deps.getSessionAnalytics({
+        days: params?.days,
+        topLimit: params?.topLimit,
+      });
+      return makeResponse(request.id, snapshot);
+    },
+
     'system.events': async (request: GatewayRequest): Promise<OutboundMessage> => {
       if (!deps.getEvents) {
         return makeResponse(request.id, { events: [] });