docs: add proactive context usage and compaction guidance

docs/api/PROTOCOL.md

@@ -60,7 +60,7 @@ sequenceDiagram
   end
 
   G->>A: process(message) in that session
-  A-->>G: streaming events (content/tool_start/tool_end)
+  A-->>G: streaming events (content/tool_start/tool_end/context_warning)
   G-->>C: events + final done
 
   C->>G: agent.cancel {connectionId}
@@ -321,6 +321,43 @@ Useful for operator dashboards and trend checks (sessions/day, message volume, t
 }
 ```
 
+#### `system.contextUsage`
+
+Return per-session estimated context-window budget snapshots.
+
+Useful for proactive compaction monitoring and operator dashboards.
+
+**Request:**
+```json
+{
+  "id": 11,
+  "method": "system.contextUsage"
+}
+```
+
+**Response:**
+```json
+{
+  "id": 11,
+  "result": {
+    "sessions": [
+      {
+        "sessionId": "ws:abc-123",
+        "budget": {
+          "estimatedTokens": 172000,
+          "contextWindow": 200000,
+          "remainingTokens": 28000,
+          "usagePct": 86,
+          "thresholdPct": 80,
+          "thresholdTokens": 160000,
+          "shouldCompact": true
+        }
+      }
+    ]
+  }
+}
+```
+
 **Response:**
 ```json
 {
@@ -589,6 +626,32 @@ Send a message to the agent and stream response.
 }
 ```
 
+`context_warning` event:
+```json
+{
+  "id": 7,
+  "event": "context_warning",
+  "data": {
+    "level": "checkpoint",
+    "message": "Context usage is 86.0% (172,000/200,000 estimated tokens). Checkpoint saved to memory namespace `session/checkpoints/ws/abc-123`.",
+    "budget": {
+      "estimatedTokens": 172000,
+      "contextWindow": 200000,
+      "remainingTokens": 28000,
+      "usagePct": 86,
+      "thresholdPct": 80,
+      "thresholdTokens": 160000,
+      "shouldCompact": true
+    },
+    "actions": {
+      "checkpointSaved": true,
+      "autoCompacted": false,
+      "checkpointNamespace": "session/checkpoints/ws/abc-123"
+    }
+  }
+}
+```
+
 `done` event:
 ```json
 {
@@ -1079,6 +1142,34 @@ Outbound attachment (image, audio, file).
 }
 ```
 
+#### `context_warning`
+
+Proactive context pressure signal emitted by `agent.send` before `done`.
+
+```json
+{
+  "id": 1,
+  "event": "context_warning",
+  "data": {
+    "level": "warning",
+    "message": "Context usage is 76.0% (152000/200000 estimated tokens).",
+    "budget": {
+      "estimatedTokens": 152000,
+      "contextWindow": 200000,
+      "remainingTokens": 48000,
+      "usagePct": 76,
+      "thresholdPct": 80,
+      "thresholdTokens": 160000,
+      "shouldCompact": false
+    },
+    "actions": {
+      "checkpointSaved": false,
+      "autoCompacted": false
+    }
+  }
+}
+```
+
 #### `done`
 
 Agent processing complete (final response).
@@ -1241,6 +1332,9 @@ class FlynnClient {
       case 'attachment':
         console.log('Attachment received:', data.mimeType);
         break;
+      case 'context_warning':
+        console.warn('Context warning:', data.level, data.message);
+        break;
       case 'done':
         console.log('Done:', data.content);
         break;
@@ -1259,6 +1353,10 @@ class FlynnClient {
     return this.sendRequest('sessions.list');
   }
 
+  async contextUsage() {
+    return this.sendRequest('system.contextUsage');
+  }
+
   async sendMessage(message, sessionId, attachments = []) {
     return this.sendRequest('agent.send', {
       message,