feat: manual context compression

[C10H14N2O5]

TL;DR

• Add a /compact command for the local Agent Runner so users can explicitly request LLM-based context compression before the automatic threshold is reached.
• Add an opt-in Manual Context Compression (Experimental) setting, disabled by default and shown only for local + llm_compress configurations.
• Reuse the existing context compressor, token estimator, provider resolution, and persisted history format without adding a ChatUI button, backend API, database migration, or remote-runner compatibility layer.
• Keep the original history when manual compression fails, returns an empty or unchanged result, or does not reduce the estimated token count; manual compression never invokes the automatic half-truncation fallback.
• Acquire the same per-session lock as normal local Agent requests and revalidate the conversation ID, history, and stop state before persistence.
• Keep WebChat progress transient while updating the context ring immediately after a successful compression: connected clients see concise progress and completion states, durable history stores only the terminal result, and the generated summary is never exposed.
• Add focused regression coverage for forced compression, command gates, permissions, checkpoints, concurrency conflicts, database verification, log privacy, and provider resolution, together with real WebUI and provider-backed manual verification.

---

Background

Fixes #9281

Related to #8348 and #9252, but intentionally does not implement configurable automatic compression thresholds.

AstrBot already supports automatic context management through maximum-turn enforcement and a token-threshold safeguard. When a request approaches the model context-window limit, ContextManager can summarize the history with an LLM or truncate it by conversation turns. However, token-triggered compression does not run until its threshold is reached. With models offering 512K, 1M, or larger context windows, users may encounter practical degradation far below the current 82% threshold:

• Agent tool calls can accumulate large intermediate outputs with little long-term value.
• Important task goals can become diluted by details in a long-running conversation.
• A completed project phase may be worth summarizing before the next phase begins.
• Re-sending a large history on every request increases latency, token consumption, and API cost.
• Users should not need to misrepresent a model's context-window size merely to trigger compression earlier.

This PR adds the manual /compact workflow available in other agent harnesses. It lets users request compression at an appropriate point without changing AstrBot's automatic threshold or existing automatic behavior.

The first version uses a command instead of a dedicated ChatUI button. AstrBot's command system already provides registration, autocomplete, enable/disable controls, renaming, and permission management. Reusing it keeps the patch reviewable while supporting WebChat and other messaging platforms without a new API or UI component.

Because an LLM-generated summary may omit role state, narrative facts, or task details, this capability is marked experimental and remains disabled by default. Users must explicitly opt in before the command can run.

---

Modifications / 改动点

1. /compact user command

Register /compact in the built-in command plugin and reuse the existing command-management behavior:

• The command can be disabled, renamed, or permission-restricted under Plugins → Manage Behaviors.
• Regular members may use it in direct messages and group chats with per-member sessions enabled.
• Shared group conversations require administrator permission, preventing regular members from changing context shared by the entire group.
• The command rejects execution when AI features are disabled.
• The command rejects execution when manual context compression is disabled.
• The command rejects non-local Agent Runners.
• The command requires the llm_compress context strategy.
• Missing conversations or unavailable compression providers produce explicit errors.

The live user-visible flow remains intentionally concise:

⏳ Compressing context...
✅ Context compressed.

The generated summary is never printed into the chat. WebChat additionally receives an agent_stats event so the context ring immediately reflects the estimated size of the compressed history.

WebChat marks the progress status as ephemeral. The live client replaces it with the terminal result, while persisted history after a successful run contains only:

user: /compact
astrbot: ✅ Context compressed.

2. Opt-in experimental setting

Add the following configuration value:

{
  "provider_settings": {
    "enable_manual_context_compression": false
  }
}

Configuration behavior:

• The default is false, so upgrading does not silently enable the feature for existing users.
• The setting is visible only when agent_runner_type=local and context_limit_reached_strategy=llm_compress.
• When another strategy or runner is selected, the setting is hidden and the command cannot execute, but the saved value is preserved.
• Chinese, English, and Russian configuration metadata include localized labels and risk guidance.
• No database field or configuration migration is introduced.

3. Reuse the existing compression flow

Add an optional force_compress argument to ContextManager.process(). Its default remains false, preserving all existing automatic callers.

With force_compress=True, the manual command:

• bypasses the 82% automatic token threshold;
• bypasses the maximum-turn gate;
• does not depend on model-metadata context-window values;
• ignores trusted token usage that is relevant only to the automatic request path;
• reuses _run_compression(), the existing TokenCounter, and the LLM summary compressor; and
• explicitly disables the post-summary half-truncation fallback.

Automatic compression retains its existing half-truncation protection. Only the manual path disables that fallback so a failed /compact operation cannot destructively truncate the original history.

4. Preserve the latest complete turn

Add an optional preserve_latest_round behavior to the LLM summary compressor. It defaults to disabled and therefore does not alter automatic compression output.

When enabled by manual compression:

• the latest complete user-assistant turn is always preserved verbatim;
• any incomplete user request or other content following that turn is preserved;
• a zero-token estimate cannot move the protected latest turn into the summary input;
• a conversation with only one complete user-assistant turn does not call the provider and reports insufficient history; and
• additional recent complete turns are retained according to llm_compress_keep_recent_ratio, without splitting logical turns.

This reduces the risk of changing the user's most recent requirements, tool state, or editable response.

5. Checkpoint-aware history persistence

The manual command reads the persisted database history and uses the existing checkpoint utilities during conversion:

• bind_checkpoint_messages() associates persisted checkpoints with their messages.
• dump_messages_with_checkpoints() serializes the compressed result.
• Checkpoints belonging to summarized historical turns are removed with those messages.
• Checkpoints on the preserved latest turn remain available, keeping WebChat edit and regenerate behavior functional.
• Runtime-only persona, tool, and safety prompts are not persisted and are injected again through the normal request path.

6. Token-benefit validation and non-destructive failure

Estimate tokens both before and after compression:

• Persistence occurs only when the estimated token count is strictly lower after compression.
• Provider failures preserve the original history.
• Empty summaries preserve the original history.
• Unchanged compressor output preserves the original history.
• Compressed histories that do not reduce the total estimated token count preserve the original history.
• Manual compression never invokes half-truncation merely because the result still exceeds the automatic threshold.

On success, the compressed history and token_usage=0 are saved in the same database update. The next normal model response refreshes token state using the provider's actual usage information.

7. Session locking, concurrency revalidation, and stop handling

/compact acquires the same unified-message-origin (UMO) session lock used by normal local Agent requests:

• It does not stop a running Agent request.
• If the same session already has an active Agent request, compression waits until that request has persisted its complete result.
• Different sessions can compact concurrently because their locks are independent.
• After acquiring the lock, the command reloads the current conversation ID and database history.
• After the summary request, it reloads the active conversation ID and persisted history again.
• If the user switches conversations, runs /new, or modifies the same history through the Dashboard/API, the result is discarded.
• The stop state is checked again immediately before persistence.
• A WebChat /stop request prevents the compressed result from being written and explicitly reports that the original history was preserved.

Dashboard and API history updates do not acquire this session lock. The additional conversation-ID and history comparisons therefore protect against external changes that occur while the LLM summary is being generated.

8. Safe verification after database exceptions

If update_conversation() raises an exception, the command does not immediately assume that persistence failed. It safely reloads the database state once:

• If the stored history already equals the target history, the write actually completed and the command continues as successful.
• If the stored history remains equal to the original history, the command reports failure and confirms preservation.
• If the stored history is a third state, the command reports an unknown context state and asks the user to inspect it before retrying.
• If verification itself fails, the command reports the same unknown state.

This covers cases where a database update commits successfully but the client still receives an exception.

9. WebChat statistics, transient progress, and log privacy

• WebChat progress uses the internal webchat_ephemeral chain type and remains visible to connected clients.
• Dashboard SSE keeps the progress state in its active-run display snapshot but excludes it from the persistence accumulator.
• Dashboard WebSocket and OpenAPI WebSocket forward the progress state without adding it to their persistence accumulators.
• Success, failure, cancellation, and unknown-state terminal messages remain durable; page refreshes and service restarts retain the user command and one terminal bot message.
• The agent_stats event is sent on a best-effort basis after persistence and after leaving the session lock.
• A statistics-delivery failure does not roll back history or misreport the completed compression as a failure.
• Platforms other than WebChat do not receive this event.
• New exception logs contain only fixed messages and exception types.
• Exception text, tracebacks, conversation history, and UMO identifiers are not logged, preventing provider or database errors from exposing sensitive context.

10. Reuse provider resolution

Refactor the existing context-compression provider resolver so both normal Agent construction and /compact can call it without changing its selection semantics:

1. Prefer the explicitly configured compression provider.
2. If that provider is unavailable, retain the existing fallback to the current session's chat provider.
3. If no compression provider ID is configured, use the current session's chat provider.
4. Reject compression when no provider is available.

Existing automatic compression provider selection remains unchanged.

---

Scope and Compatibility

This PR intentionally keeps the following boundaries:

• Only AstrBot's built-in local Agent Runner is supported.

• Dify, Coze, Alibaba Cloud Bailian, DeerFlow, and other remote runners own their context remotely; this PR does not attempt to rewrite remote history.

• No dedicated Compress now ChatUI button is added.

• No backend API or OpenAPI schema is added.

• The automatic 82% compression threshold is unchanged.

• The configurable automatic token thresholds proposed in [Feature]Token-Threshold Context Compression #8348 and [Feature] 上下文压缩阈值可配置化 #9252 are out of scope.

• The generated summary is not exposed in chat.

• No dependency or lockfile is changed.

• No database schema is changed.

• Existing configurations are neither migrated nor enabled automatically.

• Default behavior for all existing automatic compression callers remains unchanged.

• This is NOT a breaking change. / 这不是一个破坏性变更。

---

Changed Files and Size

The working tree changes 18 tracked files relative to the baseline:

Area	File	Purpose
Command	astrbot/builtin_stars/builtin_commands/commands/conversation.py	/compact gates, locking, compression, persistence, and feedback
Registration	astrbot/builtin_stars/builtin_commands/main.py	Register /compact
Compression core	astrbot/core/agent/context/compressor.py	Preserve the latest complete turn and sanitize error logging
Context configuration	astrbot/core/agent/context/config.py	Add the optional latest-turn preservation setting
Context manager	astrbot/core/agent/context/manager.py	Forced compression and manual-mode half-truncation control
Provider resolution	astrbot/core/astr_main_agent.py	Share the existing compression-provider resolver
Default configuration	astrbot/core/config/default.py	Opt-in default, schema, and conditional metadata
WebChat transport	Three Dashboard service files	Forward transient progress without persisting it across SSE and WebSocket consumers
Dashboard i18n	Three config-metadata.json files	Chinese, English, and Russian labels and risk guidance
Tests	Five test files	Compression core, command, provider resolution, SSE, and WebSocket regressions

Patch size:

18 files changed, 1218 insertions(+), 44 deletions(-)

Production Python: +378 / -35, net +343 lines
Dashboard locale metadata: +12 lines
Tests: +828 / -9, net +819 lines

Most added lines are regression tests. The implementation adds no compatibility layer, UI component, or dependency.

---

Screenshots or Test Results / 运行截图或测试结果

Test Environment

• Windows 11 Home 64-bit
• DisplayVersion: 25H2
• Build: 26200.9168
• Python: 3.12
• Node.js: 24.16.0
• pnpm: 11.19.0
• PowerShell: 7.6.4
• AstrBot baseline: c6a14e0600485293bd88cf78c04ecec967b21b50
• Tested state: final feature-branch patch relative to the baseline commit

Verification Steps

1. Enable the local Agent Runner, select the llm_compress strategy, and enable Manual Context Compression (Experimental).
2. Build the Dashboard and run the related Python regression suites listed below.
3. Create a conversation with multiple complete turns and run /compact while the context is below the automatic 82% threshold.
4. Verify the progress/completion messages, the reduced context ring, preserved visible WebChat history, and continued recall on the next turn.
5. Exercise the documented failure, concurrency, stop, permission, and configuration gates and confirm that unsuccessful operations preserve the original history.

Baseline Before Implementation

Before modifying source code, the following command was run from a clean master...origin/master worktree:

uv run pytest tests/agent/test_context_manager.py tests/test_conversation_commands.py tests/test_conversation_checkpoint.py -q --junitxml=temp/compact-baseline.xml

Result:

70 passed, 1 warning in 9.08s

The only warning was the pre-existing Python deprecation warning for audioop, which is scheduled for removal in Python 3.13.

Focused Implementation Tests

Compression core, command, checkpoint, and main-Agent provider tests:

197 passed in 11.334s

Configuration loading and configuration-metadata conversion tests:

47 passed in 6.868s

Final Related Regression

The final combined related regression used:

uv run pytest tests/agent/test_context_manager.py tests/test_conversation_commands.py tests/test_conversation_checkpoint.py tests/unit/test_astr_main_agent.py tests/unit/test_config.py -q --junitxml=temp/compact-final.xml

Result:

252 passed, 1 warning in 9.94s

The warning is identical to the baseline warning.

This regression set covers:

• automatic behavior below and above the compression threshold;
• force_compress=True bypassing automatic gates;
• disabling half-truncation in manual mode;
• preservation of the latest complete turn, active user request, system messages, and a zero-token latest turn;
• recent-context retention by complete logical turns;
• checkpoint binding, serialization, removal, editing, and regeneration boundaries;
• gates for the global AI setting, experimental setting, runner, strategy, provider availability, and shared-group permissions;
• successful persistence and WebChat agent_stats delivery;
• empty summaries, provider exceptions, unchanged summaries, and summaries without a token benefit;
• active-conversation and persisted-history conflicts;
• stop requests and the final pre-persistence stop check;
• target/original/other/error verification states after a database update exception;
• best-effort statistics delivery without changing a successful outcome;
• exception logs that omit history, UMO, exception text, and tracebacks;
• dedicated providers, current-session provider fallback, and no-provider cases; and
• configuration defaults, completion, and i18n key conversion.

Local Tool Loop Agent Runner Regression

To verify that the optional ContextManager.process() argument does not affect the normal local Agent request path:

uv run pytest tests/test_tool_loop_agent_runner.py -q --junitxml=temp/compact-runner.xml

Result:

40 passed, 1 warning in 4.943s

The warning is the same pre-existing audioop deprecation warning.

Final Combined Regression

The final combined run covers the command, compression, provider, runner, session-lock, configuration, Dashboard SSE, Dashboard WebSocket, and OpenAPI WebSocket suites:

uv run python -B -m pytest tests/test_conversation_commands.py tests/agent/test_context_manager.py tests/unit/test_astr_main_agent.py tests/test_tool_loop_agent_runner.py tests/unit/test_session_lock.py tests/unit/test_config.py tests/test_chat_route.py tests/unit/test_live_chat_service.py tests/unit/test_open_api_service_ws.py -p no:cacheprovider -q

Result:

316 passed, 1 warning in 8.50s

There were no failures, errors, or skips. The warning was the same pre-existing audioop deprecation warning.

The WebChat suites cover transient progress forwarding, active-run snapshots, terminal-message replacement, and single-row persistence across Dashboard SSE, Dashboard WebSocket, and OpenAPI WebSocket.

Formatting and Static Checks

ruff format --check .
501 files already formatted

ruff check .
All checks passed!

git diff --check
No whitespace errors

git diff --check emitted only Windows working-tree LF/CRLF conversion notices and no whitespace errors.

All three Chinese, English, and Russian config-metadata.json files were also validated as parseable JSON.

Dashboard Production Build

The following command was run from the dashboard directory:

pnpm build

Result:

vue-tsc --noEmit
vite build
3795 modules transformed
✓ built in 31.45s
Exit code: 0

Recommended Neo Profile on Windows

The CONTRIBUTING.md Neo profile was also run with dependency synchronization skipped because the environment was already synchronized:

scripts/pr_test_env.sh --profile neo --skip-sync

Ruff passed. The Neo test selection completed with 11 passed, 2 failed, 2 warnings. Both failures are existing Windows path-separator assertions in tests/test_computer_skill_sync.py: the tests expect skills/skills.zip, while the Windows implementation returns skills\skills.zip. Neither that test file nor astrbot/core/computer/computer_client.py is modified by this patch.

An AstrBot instance launched from this checkout with main.py --webui-dir dashboard/dist responded successfully at http://127.0.0.1:6185 with HTTP 200.

Manual WebUI and Runtime Verification

Real WebChat, the local Agent Runner, and an LLM provider were used for the following manual verification.

Successful manual compression

• Ran /compact while the context was well below the automatic 82% threshold.
• Set Maximum conversation turns before compression to -1 or above the current turn count.
• Confirmed that Dashboard SSE and Dashboard WebSocket show the progress status while compression is running and replace it with the terminal result.
• Confirmed that page refreshes and service restarts retain user: /compact plus one terminal bot message without a persisted ⏳ Compressing context... entry.
• Confirmed that no summary body, empty message, or stuck loading state appeared.
• Confirmed that the context ring dropped immediately and remained consistent after refreshing the page.
• Confirmed that the original visible WebChat messages remained unchanged.
• Confirmed that the next conversation turn could still recall earlier facts.
• Repeated compression twice and verified that the original memory anchor remained accurate.
• Confirmed that editing and regenerating the latest message still worked.

One successful run recorded:

Compress completed. 7418 -> 3813 tokens.
✅ Context compressed.

Observed behavior:

WebChat compression and Context Ring change

QQ Official Bot

Failure preserves the original history

The compression prompt was temporarily changed to request expansion, verifying that output without a token reduction is never persisted:

Compress completed. 11454 -> 11473 tokens.
❌ Context compression failed; the original context was preserved.

The following failure paths were also verified:

• invalid API key or unreachable provider;
• both the current chat provider and dedicated compression provider unavailable;
• only one complete user-assistant turn;
• manual compression disabled;
• global AI setting disabled; and
• strategy changed to turn-based truncation.

None of these tested paths reduced the context ring, half-truncated history, or damaged subsequent recall.

Original history and Context Ring remain unchanged after failure

Session isolation and concurrency

• Compacting session A left session B's context ring and history unchanged.
• Sessions A and B could compact concurrently without blocking each other.
• Repeating /compact twice in the same session did not restore stale history or drop the latest turn.
• When the same session had a slow Agent response, /compact waited for it and then compressed history containing the completed response.
• Running /new or modifying history through another entry point during compression prevented persistence:

⚠️ Context changed during compression; no changes were saved.

Stop behavior

A WebChat stop request cannot immediately cancel every in-flight provider request, but it prevents the result from being persisted. After the provider returned, the command reported:

⚠️ Compression cancelled; original context was preserved.

History and the context ring remained unchanged. This protects persisted state, although a slow provider request may still run to completion and incur cost, as noted under Known Limitations.

Configuration and i18n

• The setting is disabled by default.
• Its value persists after saving and refreshing.
• Switching to turn-based truncation hides the setting; switching back restores the saved value.
• Switching to a remote runner hides the context-management section; switching back to local restores it.
• Disabling the global AI setting hides the section.
• The saved configuration JSON contains enable_manual_context_compression.
• The current dashboard/dist was used to verify the Chinese, English, and Russian labels and risk guidance, with no raw i18n keys shown.
• The displayed titles were 手动上下文压缩（实验性）, Manual Context Compression (Experimental), and Ручное сжатие контекста (экспериментальная функция), with complete localized risk guidance in each language.

Observed configuration:

Simplified Chinese (zh-CN)

English (en-US)

Russian (ru-RU)

---

Known Limitations

• Only the local Agent Runner is supported; remote runners manage their context externally.
• A WebChat stop request prevents persistence but cannot guarantee immediate cancellation of every provider HTTP request.
• The context ring uses an estimate from the compressed history until the next normal model response updates it with actual provider usage.
• Like other callers of ConversationManager.update_conversation(), the final update is not a database-level compare-and-swap. This path mitigates concurrent changes by re-reading and comparing the active conversation and persisted history immediately before the update.

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Enable safe, experimental manual context compression through the local Agent Runner while preserving existing automatic behavior and conversation integrity.

New Features:

• Add an opt-in /compact command for manually compressing context in local LLM-compression sessions.
• Expose experimental manual compression configuration with conditional multilingual dashboard metadata.

Bug Fixes:

• Prevent failed, ineffective, concurrent, stopped, or unverifiable compression attempts from overwriting conversation history.
• Keep transient WebChat compression progress out of durable message history while preserving terminal results and context statistics.
• Protect sensitive conversation and provider details from compression-related exception logs.

Enhancements:

• Extend context compression to support forced execution while preserving automatic compression behavior and avoiding destructive fallback truncation.
• Preserve the latest complete conversation turn and its checkpoints during manual compression.
• Share compression-provider resolution between normal agent construction and manual compression.

Tests:

• Add regression coverage for compression behavior, command gates, checkpoints, concurrency, cancellation, persistence verification, provider resolution, log privacy, and WebChat transports.