docs: add proactive context usage and compaction guidance
This commit is contained in:
William Valentin
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
+99
-1
@@ -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,
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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": {
|
||||
|
||||
Reference in New Issue
Block a user