feat(adapters): context mgmt in anthropic and openai_responses (#3049)

Author: olimorris

.codecompanion/ui.md

@@ -56,6 +56,7 @@ Manages the overlaying of icons in the chat buffer for tools, based on their sta
 
 ### Tests
 
-@./tests/interactions/chat/test_builder.lua
+@./tests/interactions/chat/ui/test_builder_state.lua
+@./tests/interactions/chat/ui/test_fold_reasoning_output.lua
 
 Comprehensive tests for the builder pattern covering state management, section detection, reasoning transitions, and header logic. Tests verify that the builder correctly manages formatting state across multiple message additions and properly detects when new sections or headers are needed.

.github/workflows/copilot-setup-steps.yml

@@ -128,7 +128,7 @@ export default withMermaid(
         { text: "Introduction", link: "/" },
         { text: "Installation", link: "/installation" },
         { text: "Getting Started", link: "/getting-started" },
-        { text: "Upgrading", link: "/upgrading" },
+        { text: "Architecture", link: "/architecture" },
         {
           text: "Agent Client Protocol (ACP)",
           link: "agent-client-protocol",
@@ -141,6 +141,8 @@ export default withMermaid(
           text: "Configuration",
           collapsed: true,
           items: [
+            { text: "Upgrading", link: "/configuration/upgrading" },
+
             { text: "Action Palette", link: "/configuration/action-palette" },
             { text: "Adapters - ACP", link: "/configuration/adapters-acp" },
             { text: "Adapters - HTTP", link: "/configuration/adapters-http" },

doc/.vitepress/config.mjs

@@ -0,0 +1,26 @@
+---
+description: Architectural concepts and design principles behind CodeCompanion.
+---
+
+# Architecture
+
+This section of the documentation covers architectural concepts and design principles that underpin CodeCompanion's functionality.
+
+This is not mandatory reading for users of CodeCompanion. It may be of interest to those who are looking to understand some of the technical details of how CodeCompanion works, or those who are looking to contribute to the project.
+
+## How Context Is Managed
+
+One of the limitations of working with LLMs is that of context, as they have a finite window with which they can respond to a user's ask. That is, there's only a certain amount of data that LLMs can reference in order to generate a response. To equate this to human terms, it can be thought of as [working memory](https://en.wikipedia.org/wiki/Working_memory) and it varies greatly depending on what model you're using. The context window is measured in [tokens](https://platform.claude.com/docs/en/about-claude/glossary#tokens).
+
+When a user breaches the context window, the conversation **ends** and it **cannot** continue. This can be hugely inconvenient in the middle of a coding session and potentially time consuming to recover from. CodeCompanion has context awareness which means it can prevent this from happening by taking **preventative** action.
+
+### In the Chat Buffer
+
+> [!NOTE]
+> CodeCompanion enables context management by default
+
+If you're using the `openai_responses` or `anthropic` adapters, then CodeCompanion will use their native server-side compaction capabilities. Please see their respective documentation [here](https://developers.openai.com/api/docs/guides/compaction) and [here](https://platform.claude.com/docs/en/build-with-claude/compaction) for more information.
+
+To be updated...
+
+Firstly, CodeCompanion manages context by paying close attention to the number of tokens in the [chat buffer](/usage/chat-buffer/index), matching them against a defined trigger threshold in your config, which can be [customised](/configuration/chat-buffer#context-management).