feat(gateway): expose context usage and warning events

src/gateway/handlers/system.ts

@@ -13,6 +13,20 @@ export interface TokenUsageEntry {
   total: { inputTokens: number; outputTokens: number; calls: number; estimatedCost: number };
 }
 
+/** Per-session context budget report returned by system.contextUsage. */
+export interface ContextUsageEntry {
+  sessionId: string;
+  budget: {
+    estimatedTokens: number;
+    contextWindow: number;
+    remainingTokens: number;
+    usagePct: number;
+    thresholdPct: number;
+    thresholdTokens: number;
+    shouldCompact: boolean;
+  };
+}
+
 export interface PresenceEntry {
   channel: string;
   senderId: string;
@@ -63,6 +77,8 @@ export interface SystemHandlerDeps {
   getUsage?: () => { totalSessions: number; activeConnections: number };
   /** Optional callback to retrieve per-session token usage data. */
   getTokenUsage?: () => TokenUsageEntry[];
+  /** Optional callback to retrieve per-session context budget data. */
+  getContextUsage?: () => ContextUsageEntry[];
   /** Optional callback to retrieve aggregated metrics snapshot. */
   getMetrics?: () => MetricsSnapshot;
   /** Optional callback to retrieve session analytics. */
@@ -202,6 +218,11 @@ export function createSystemHandlers(deps: SystemHandlerDeps) {
       return makeResponse(request.id, { sessions });
     },
 
+    'system.contextUsage': async (request: GatewayRequest): Promise<OutboundMessage> => {
+      const sessions = deps.getContextUsage?.() ?? [];
+      return makeResponse(request.id, { sessions });
+    },
+
     'system.metrics': async (request: GatewayRequest): Promise<OutboundMessage> => {
       if (!deps.getMetrics) {
         return makeResponse(request.id, {});