From 9c8da4161087494b4c656e8f5e27b540c213a16e Mon Sep 17 00:00:00 2001 From: William Valentin Date: Mon, 16 Feb 2026 15:44:13 -0800 Subject: [PATCH] docs: add proactive context usage and compaction guidance --- README.md | 24 +++++++++ config/default.yaml | 17 +++++++ docs/api/PROTOCOL.md | 100 ++++++++++++++++++++++++++++++++++++- docs/performance/TUNING.md | 15 ++++++ docs/plans/state.json | 32 ++++++++++++ 5 files changed, 187 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ff0e267..7eff0e2 100644 --- a/README.md +++ b/README.md @@ -961,6 +961,30 @@ When the selected backend is unavailable (for example embedding provider errors) `memory.auto_extract` controls whether compaction appends extracted durable facts to `global` memory. +### Proactive Context Management + +Flynn can proactively signal context pressure, checkpoint conversation state to memory, and auto-compact before hard context overflows. + +```yaml +compaction: + enabled: true + threshold_pct: 80 + keep_turns: 4 + summary_max_tokens: 1024 + importance_threshold: 1 + proactive: + enabled: true + warn_pct: 75 + checkpoint_pct: 85 + auto_compact_pct: 95 + checkpoint_cooldown_ms: 300000 + memory_namespace: session/checkpoints +``` + +Gateway surfaces this via: +- `context_warning` streamed event during `agent.send` (before `done`) +- `system.contextUsage` RPC for per-session context budget snapshots + ### Embedding Config Fields | Field | Required | Description | diff --git a/config/default.yaml b/config/default.yaml index 856397b..9476a0d 100644 --- a/config/default.yaml +++ b/config/default.yaml @@ -218,6 +218,23 @@ hooks: # extra_sections: [] # context_level: normal # minimal | normal | detailed | debug +# ── Context Compaction ──────────────────────────────────────────────── +# Optional proactive context monitoring and checkpointing. +# +# compaction: +# enabled: true +# threshold_pct: 80 +# keep_turns: 4 +# summary_max_tokens: 1024 +# importance_threshold: 1 +# proactive: +# enabled: false +# warn_pct: 75 +# checkpoint_pct: 85 +# auto_compact_pct: 95 +# checkpoint_cooldown_ms: 300000 +# memory_namespace: session/checkpoints + # skills: # # Registry catalog source for discovery and install-by-id: # # local path or HTTPS URL. Can also be set via FLYNN_SKILLS_REGISTRY_SOURCE. diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index 2470d74..965a56f 100644 --- a/docs/api/PROTOCOL.md +++ b/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, diff --git a/docs/performance/TUNING.md b/docs/performance/TUNING.md index 6568d74..22b7a94 100644 --- a/docs/performance/TUNING.md +++ b/docs/performance/TUNING.md @@ -71,6 +71,21 @@ keepTurns: 10 # More history summaryMaxTokens: 4096 # Detailed summaries ``` +### Proactive Compaction Signals + +Use proactive thresholds to checkpoint before compaction cliffs and emit warning telemetry: + +```yaml +compaction: + proactive: + enabled: true + warn_pct: 75 + checkpoint_pct: 85 + auto_compact_pct: 95 + checkpoint_cooldown_ms: 300000 + memory_namespace: session/checkpoints +``` + ### Context Depth Levels Control how much context is injected into the system prompt: diff --git a/docs/plans/state.json b/docs/plans/state.json index 2fd3b35..5b65893 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -3500,6 +3500,38 @@ "docs/plans/state.json" ], "test_status": "pnpm typecheck + pnpm test:run src/cli/setup/channels.test.ts src/cli/setup/config.test.ts src/cli/setup/integration.test.ts src/cli/setup/sections.test.ts src/daemon/routing.test.ts src/gateway/handlers/services.test.ts src/gateway/tailscale.test.ts src/models/local/llamacpp.test.ts src/models/local/ollama.test.ts src/models/openai.baseurl.test.ts src/tools/executor.test.ts src/tools/registry.test.ts passing" + }, + "proactive-context-usage-and-compaction-signals": { + "status": "completed", + "date": "2026-02-16", + "updated": "2026-02-16", + "summary": "Implemented proactive context-window management end-to-end: orchestrator now exposes estimated context budget, emits staged context alerts, writes checkpoint summaries to memory near threshold, and can auto-compact proactively. Gateway now emits `context_warning` stream events during `agent.send`, serves `system.contextUsage` snapshots, and dashboard usage UI includes context budget visibility. Added config schema support under `compaction.proactive`, mapped runtime wiring in both WS SessionBridge and channel routing paths, and updated protocol/docs/default config examples with focused tests.", + "files_modified": [ + "src/context/compaction.ts", + "src/backends/native/prompts.ts", + "src/backends/native/orchestrator.ts", + "src/backends/native/orchestrator.test.ts", + "src/config/schema.ts", + "src/config/schema.test.ts", + "src/gateway/session-bridge.ts", + "src/daemon/routing.ts", + "src/gateway/protocol.ts", + "src/gateway/protocol.test.ts", + "src/gateway/handlers/agent.ts", + "src/gateway/handlers/agent.test.ts", + "src/gateway/handlers/system.ts", + "src/gateway/handlers/handlers.test.ts", + "src/gateway/server.ts", + "src/daemon/services.ts", + "src/gateway/ui/pages/chat.js", + "src/gateway/ui/pages/usage.js", + "docs/api/PROTOCOL.md", + "README.md", + "docs/performance/TUNING.md", + "config/default.yaml", + "docs/plans/state.json" + ], + "test_status": "pnpm test:run src/backends/native/orchestrator.test.ts src/config/schema.test.ts src/gateway/handlers/agent.test.ts src/gateway/handlers/handlers.test.ts src/gateway/protocol.test.ts + pnpm typecheck passing" } }, "overall_progress": {