Skill: maverick-software/compaction-ui-enhancements (version 2.3.0)

--- name: compaction-ui version: 2.3.0 description: "Background memory compaction with auto-trigger, chat summary paragraph, configurable threshold, model selector, settings tab, and result storage for OpenClaw Control UI." --- # Compaction UI v2.1.0 Memory compaction system for the OpenClaw Control UI — background execution with toast notifications, auto-trigger at configurable token thresholds, conversation summary paragraphs in compacted output, dedicated settings tab with model selector, and result history. ## Status: ✅ Active | Component | Status | |-----------|--------| | Context Gauge Button | ✅ Working | | Background Compaction (toast) | ✅ Working | | Auto-Compaction Trigger | ✅ Working | | Conversation Summary Paragraph | ✅ Working | | Settings Tab (plugin-registered) | ✅ Working | | Model Selector | ✅ Working | | Last Result Storage + Viewer | ✅ Working | | Settings Persistence & Reload | ✅ Working | | Auth Hierarchy (OAuth > API > Fallback) | ✅ Working | | Chat History Filters | ✅ Working | | Full Background Isolation (no chat interference) | ✅ Working | ## Features ### 1. Context Gauge Button (`app-render.helpers.ts`) A circular SVG progress ring in the chat toolbar that doubles as the manual compact trigger. - **Placement:** After session selector dropdown in `renderChatControls()` - **Data source:** `sessionsResult.sessions[].totalTokens` and `contextTokens` from session rows - **Colors:** Green (<60%), Yellow (60-85%), Red (≥85%) - **Disabled:** When utilization <20% or during active compaction - **Tooltip:** Shows "Context: XK / YK tokens (Z%)" ### 2. Background Compaction (Toast) On click (or auto-trigger), compaction runs in the background using the standard bottom-right toast system — **no blocking modal**. The UI remains fully interactive. - **Running toast:** Shows "Memory Compaction" with spinner - **Complete toast:** Shows "Compacted: XK → YK" with checkmark (auto-dismisses after 5s) - **Error toast:** Shows failure message (auto-dismisses after 5s) - Uses `backgroundJobToasts` system consistent with all other background processes (cron, knowledge extraction, etc.) ### 3. Auto-Compaction After every chat response (`final` event), the UI checks token usage against the configured threshold. If exceeded: - Background compaction triggers automatically - Toast shows "Auto-Compacting (X%)" with the current utilization - 5-minute debounce prevents repeated triggers - Chat refreshes automatically after successful compaction - Silent toast removal if nothing was compacted ### 4. Conversation Summary Paragraph Every compaction output now begins with a `## Conversation Summary` section **before** the structured `## Goal` section. This is a 3-6 sentence natural language paragraph that: - Describes the overall topic(s) of the conversation - Explains the flow of discussion and key transitions - Summarizes how the conversation progressed - Written in past tense as a narrative overview **Implementation:** Custom instructions are injected into the upstream compaction LLM call via `compact.ts`. The instruction is prepended to any user-provided custom instructions (from `/compact [instructions]`), so both coexist. **Example output:** ``` ## Conversation Summary The conversation began with the user requesting improvements to the compaction system, specifically moving from a blocking modal to background toasts. Discussion then shifted to adding a settings tab with auto-compaction controls. After implementing and testing those features, the user noticed settings weren't persisting across tab navigations, which led to a fix for the module-level state cache. Finally, the user requested adding a narrative summary paragraph to the compaction output for better context. ## Goal ... ``` ### 5. Settings Tab (Plugin-Registered) A dedicated Compaction tab under the **Agent** navigation group, registered via the Plugin UI architecture. **Registration:** `plugins-ui.ts` → `BUILTIN_UI_VIEWS` with `id: "compaction"`, `group: "agent"`, `position: 7`, `icon: "archive"` **Cards:** #### Auto-Compaction Card - **Toggle:** Enable/disable automatic compaction - **Threshold slider:** 10% to 95% (default: 60%) - **Color-coded:** Green (<60%), Yellow (60-85%), Red (≥85%) #### Model Card - **Dropdown:** Select a specific model for compaction or use session default - **Grouped by provider** with context window sizes shown - **Warning callout** when custom model selected (API key reminder) - **Fallback:** If custom model fails, automatically falls back to session default #### Result Storage Card - **Toggle:** Opt-in to save the compacted summary text for review #### Last Compaction Card - **Before/After:** Large styled token counts in a 2-column grid - **Stats:** Tokens saved, percent reduction, trigger type, timestamp, session key - **View Results:** Expandable summary viewer (when storage is enabled) - **Clear:** Reset stored result - **Hint:** Shows "Enable Store Results" message when storage is off **State Management:** - Module-level state persists across re-renders within a session - Settings reload from backend every time the tab is visited (2-second staleness threshold) - `resetCompactionSettingsState()` exported for tests and tab switches ### 6. Auth Hierarchy Compaction uses `resolveApiKeyForProvider` via `getApiKeyForModel` — the same auth chain as chat: **OAuth → API Key → Fallback** No separate configuration needed. If OAuth (Claude Max) is configured as the primary auth profile, compaction uses it automatically. Custom model selection uses this same auth chain independently. ### 7. Result Storage When enabled, the most recent compaction result is persisted to `{agentDir}/compaction-config.json`: ```json { "settings": { "autoEnabled": true, "autoThresholdPercent": 60, "storeLastResult": true, "compactionModel": "anthropic/claude-sonnet-4-6" }, "lastResult": { "timestamp": 1709283600000, "trigger": "manual", "tokensBefore": 50614, "tokensAfter": 4766, "tokensSaved": 45848, "percentReduction": 91, "sessionKey": "agent:main:main", "summary": "## Conversation Summary\nThe conversation focused on...\n\n## Goal\n..." } } ``` When storage is disabled, metadata (timestamps, token counts) is still saved but the summary text is omitted. ### 8. Chat History Filters - **NO_REPLY/HEARTBEAT_OK filtering:** Skips assistant messages with these exact texts - **Compaction divider:** Renders labeled divider line for `__openclaw.kind === "compaction"` messages ## Architecture ### Backend RPCs | Method | Description | |--------|-------------| | `sessions.compact` | Execute compaction (records result after completion) | | `compaction.getSettings` | Read settings from config file | | `compaction.saveSettings` | Update settings (threshold auto-clamped 10-95%) | | `compaction.getLastResult` | Get stored last compaction result | | `compaction.clearLastResult` | Clear stored result | ### Files Modified | File | Purpose | |------|---------| | `src/gateway/server-methods/compaction.ts` | Settings RPCs, config I/O, result recording | | `src/gateway/server-methods/sessions.ts` | `sessions.compact` RPC (records result after compaction) | | `src/gateway/server-methods/plugins-ui.ts` | Plugin view registration | | `src/gateway/server-methods.ts` | Handler wiring | | `src/gateway/server-methods-list.ts` | Method registration | | `src/gateway/method-scopes.ts` | Scope registration | | `src/agents/pi-embedded-runner/compact.ts` | Chat summary instruction injection | | `ui/src/ui/app-render.helpers.ts` | Context gauge + background toast trigger | | `ui/src/ui/app-gateway.ts` | Auto-compaction check after final event | | `ui/src/ui/views/compaction-settings.ts` | Settings tab view | | `ui/src/ui/app-render.ts` | View wiring + import | | `ui/src/ui/views/chat.ts` | Chat history filters | ### Config File `{agentDir}/compaction-config.json` — per-agent, created on first settings save. ### Plugin Registration The compaction tab is registered as a builtin plugin view in `plugins-ui.ts`: ```typescript { id: "compaction", label: "Compaction", subtitle: "Memory Management", icon: "archive", group: "agent", position: 7, pluginId: "compaction-ui", } ``` ## Known Gotchas - **Settings not persisting across tab visits:** Fixed in v2.1.0. The module-level `_state.loaded` flag was preventing reloads. Now reloads every 2 seconds when re-entering the tab. - **Model selector requires API keys:** If you select a custom model, make sure the provider's API key is configured. The UI shows a warning callout. - **Compaction model format:** Must be `"provider/model"` format (e.g. `"anthropic/claude-sonnet-4-6"`). Invalid formats are silently ignored and fall back to session default. - **parentId skip-set propagation must be message-only:** When filtering memory flush messages from `readSessionMessages`, the skip set must ONLY propagate through entries with a `message` field. Non-message protocol entries (`type:"custom"`) bridge between logical turns — if their IDs enter the skip set, the entire remaining conversation gets hidden. The fix: only check `parsed?.message` entries against the skip set, and only add their IDs to it. - **No blocking modal — ever:** The gauge button in `app-render.helpers.ts` must NEVER render a full-screen overlay modal. Compaction is a background process; all status is communicated via the bottom-right toast system. Remove any `position:fixed; inset:0` overlay conditioned on `compactState.phase`. The button may show a spinner icon while running, but must not block the UI. ## Changelog ### v2.1.0 - **Conversation summary paragraph:** Compaction output now starts with a `## Conversation Summary` narrative paragraph before structured sections - **Model selector:** Choose a specific model for compaction or use session default, with provider-grouped dropdown - **Settings reload fix:** Tab now reloads settings from backend every 2s instead of caching forever - **Reference files updated:** Synced `references/` with current source ### v2.0.0 - **Background compaction:** Replaced blocking full-screen modal with background job toast - **Auto-compaction:** Triggers after chat response when token usage exceeds threshold (configurable, default 60%, 5-minute debounce) - **Settings tab:** Plugin-registered Compaction tab under Agent nav group - **Result recording:** `sessions.compact` records before/after token counts and optional summary - **Auth hierarchy:** Same OAuth → API → Fallback chain as chat - **Settings RPCs:** `compaction.getSettings`, `compaction.saveSettings`, `compaction.getLastResult`, `compaction.clearLastResult` ### v1.0.0 - Initial release: Context gauge button, blocking modal with animated phases, `sessions.compact` RPC with LLM summarization, chat history NO_REPLY/HEARTBEAT_OK filtering, compaction divider lines


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)