Implement context compaction to handle long-running tasks

- Add token usage tracking to Context class to monitor cumulative LLM usage
- Implement need_compaction property that triggers when usage exceeds 80% of context window
- Add compact() method that uses LLM to summarize conversation history with structured format
- Add _format_history_for_compaction() to format messages for summarization
- Integrate compaction checks at start of each agent step in both sync and async loops
- Update token usage after each LLM invocation
- Emit events when compaction occurs for visibility
- Add compact.md template with detailed instructions for history summarization
- Preserve system messages and error tracking through compaction cycle

This allows agents to continue working on extended tasks without hitting context window limits.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: Jeomon

windows_use/agent/context/prompt/compact.md

@@ -0,0 +1,53 @@
+Compress the conversation history into a concise continuation prompt. The agent will NOT have access to prior messages.
+
+IMPORTANT: Structure your response EXACTLY as follows:
+
+## TASK
+[State the original user task in 1-2 sentences. What does the user want the agent to accomplish?]
+
+## PROGRESS SUMMARY
+[List all completed actions since the task started:
+- Windows/applications opened or closed
+- UI elements found and interacted with (include element names, control types, coordinates)
+- Data entered, extracted, or verified
+- Navigation completed (which pages visited, URLs accessed)
+- Decisions made and why (e.g., "clicked Search instead of Browse because it's faster")
+- Obstacles encountered and how they were resolved
+- Actions that FAILED and should NOT be retried with same approach]
+
+## CURRENT SITUATION
+[Describe the present state:
+- **Active window**: Name and control type of currently visible window
+- **Recent action**: What was just executed and its result
+- **Current UI state**: What elements are visible on screen (major controls, buttons, text)
+- **Last known coordinates**: Important element positions if relevant to next step
+- **Data state**: Any extracted information, form fields filled, values entered
+- **Failures to avoid**: What approaches didn't work and why]
+
+## INSIGHTS & PATTERNS
+[What has the agent learned about this task?
+- Which UI elements consistently work vs have issues
+- How to efficiently navigate this application
+- Edge cases encountered (e.g., popups, delays, element state changes)
+- Best sequence of actions discovered
+- Application quirks or timing requirements
+- Any looping detected that should be avoided
+- LLM patterns (which reasoning approaches worked, which ones led to errors)]
+
+## NEXT ACTION
+[What should happen immediately next?
+- Tool to use (click_tool, type_tool, scroll_tool, etc.)
+- Exact target (element name, coordinates, or control type to find)
+- Expected outcome
+- Fallback if this action fails]
+
+## CRITICAL STATE
+[Preserve only essential info for continuation:
+- Open window/application names
+- Form data already entered (field → value pairs)
+- Extracted data that answers the task
+- Navigation breadcrumbs (back button locations, URL history)
+- Known element identifiers or locations
+- Any credentials or sensitive data entered (for reuse if needed)]
+
+Be concise but complete—this replaces all prior conversation history. Include only what's necessary to continue effectively.

windows_use/agent/context/service.py

@@ -1,4 +1,5 @@
-from windows_use.messages import SystemMessage, HumanMessage, ImageMessage
+from windows_use.messages import SystemMessage, HumanMessage, ImageMessage, AIMessage, ToolMessage, BaseMessage
+from windows_use.providers import BaseChatLLM,TokenUsage
 from windows_use.agent.desktop.views import Browser
 from windows_use.agent.desktop.service import Desktop
 from concurrent.futures import ThreadPoolExecutor
@@ -12,6 +13,8 @@
 
 _template_cache: dict[str, str] = {}
 
+_NON_TOOL_PARAMS = {"thought"}
+
 
 def _load_template(filename: str) -> str:
     """Load a prompt template from disk, caching after first read."""
@@ -23,6 +26,10 @@ def _load_template(filename: str) -> str:
 
 
 class Context:
+    def __init__(self,llm: BaseChatLLM):
+        self.token_usage:TokenUsage=TokenUsage()
+        self.llm = llm
+        
     def _build_system_prompt(self,
         mode: Literal["flash", "normal"],
         desktop: Desktop,
@@ -65,6 +72,60 @@ def _build_system_prompt(self,
             case _:
                 raise ValueError(f"Invalid mode: {mode} (must be 'flash' or 'normal')")
 
+    def _format_history_for_compaction(self,messages: list[BaseMessage]) -> str:
+        lines=['Following is the conversation that needs to be compacted:']
+        for message in messages:
+            content=message.content[:2000]+'...[TRUNCATED]' if len(message.content)>2000 else message.content
+            if isinstance(message,SystemMessage):
+                pass
+            elif isinstance(message,(HumanMessage)):
+                lines.append(f'USER: {content}')
+            elif isinstance(message,AIMessage):
+                lines.append(f'ASSISTANT: {content}')
+            elif isinstance(message,ToolMessage):
+                id=message.id
+                name=message.name
+                params=message.params
+                if 'thought' in params:
+                    lines.append(f'THOUGHT: {params["thought"]}')
+                lines.append(f'TOOL CALL {id}: {name}({', '.join([f'{k}={v[:2000]+'...[TRUNCATED]' if len(v)>2000 else v}' for k,v in params.items() if k not in _NON_TOOL_PARAMS])})')
+                lines.append(f'TOOL RESULT {id}: {content}')
+            else:
+                pass
+        return '\n\n---\n\n'.join(lines)
+
+    @property
+    def need_compaction(self)->bool:
+        metadata=self.llm.get_metadata()
+        context_window=metadata.context_window
+        total_tokens=self.token_usage.total_tokens
+        return total_tokens>context_window*0.8
+
+    def compact(
+        self,
+        messages: list[BaseMessage],
+        ) -> str|None:
+        template=_load_template("compact.md")
+        compaction_messages=[
+            SystemMessage(content=template),
+            HumanMessage(content=self._format_history_for_compaction(messages))
+        ]
+        llm_response=self.llm.invoke(compaction_messages)
+        return f'''
+# Context Restoration (Previous Session Compacted)
+
+The previous conversation was compacted due to context window limitations. Below is the detailed summary of work done so far.
+
+**CRITICAL: Don't repeat already completed ACTIONS**
+
+---
+
+{llm_response.content}
+
+---
+
+Continue work from where the previous session left off. FOCUS only on the remaining tasks.
+'''
 
     def system(
         self,
@@ -133,4 +194,7 @@ def _build_state_prompt(
         })
 
     def task(self, task: str) -> HumanMessage:
-        return HumanMessage(content=f"TASK: {task}")
+        return HumanMessage(content=f"TASK: {task}")
+
+    def update_token_usage(self,token_usage:TokenUsage):
+        self.token_usage=token_usage

windows_use/agent/service.py

@@ -9,7 +9,7 @@
 from windows_use.agent.desktop.service import Desktop
 from windows_use.agent.desktop.views import Browser
 from windows_use.agent.loop import LoopGuard
-from windows_use.providers.events import LLMEventType
+from windows_use.providers.events import LLMEventType, LLMStreamEventType
 from typing import Callable, Literal, TYPE_CHECKING
 from windows_use.agent.context import Context
 from windows_use.agent.base import BaseAgent
@@ -105,7 +105,7 @@ def __init__(
         self.telemetry = ProductTelemetry()
         self.watchdog = WatchDog()
         self.console = Console()
-        self.context = Context()
+        self.context = Context(llm=llm)
         self.log_to_file = log_to_file
         self.log_to_console = log_to_console
         self.llm = llm
@@ -168,6 +168,12 @@ def loop(self) -> AgentResult:
         for step in range(self.state.max_steps):
             self.state.step = step
 
+            if self.context.need_compaction:
+                messages=self.state.messages+self.state.error_messages
+                if content:=self.context.compact(messages):
+                    self.state.messages = [self.system_message, HumanMessage(content=content)]
+                self.state.error_messages.clear()
+
             # Check for loops and build state message with nudge
             nudge = None if self.disable_loop_detection else self._loop_guard.check()
             state_msg = self.context.state(
@@ -190,10 +196,12 @@ def loop(self) -> AgentResult:
             # Reason: call LLM, retry on failure, return ToolMessage
             message: ToolMessage | None = None
             last_error: Exception | None = None
+            llm_errors: list[dict] = []
             for attempt in range(self.state.max_consecutive_failures):
                 try:
                     messages = list(chain(self.state.messages, self.state.error_messages))
                     llm_event = self.llm.invoke(messages=messages, tools=self.tools)
+                    self.context.update_token_usage(llm_event.usage)
                     match llm_event.type:
                         case LLMEventType.TOOL_CALL:
                             message = ToolMessage(
@@ -209,8 +217,37 @@ def loop(self) -> AgentResult:
                             )
                             self.state.error_messages.extend([ai_message, human_message])
                             continue
+                        case LLMEventType.ERROR:
+                            # Emit LLM error event
+                            llm_error_data = {
+                                "step": step,
+                                "attempt": attempt + 1,
+                                "provider": self.llm.provider,
+                                "model": self.llm.model_name,
+                                "error_type": type(llm_event).__name__,
+                                "error": str(llm_event),
+                            }
+                            self.event.emit(
+                                AgentEvent(type=EventType.ERROR, data=llm_error_data)
+                            )
+                            llm_errors.append(llm_error_data)
+                            continue
                 except Exception as e:
                     last_error = e
+                    # Emit LLM error event for exception
+                    llm_error_data = {
+                        "step": step,
+                        "attempt": attempt + 1,
+                        "provider": self.llm.provider,
+                        "model": self.llm.model_name,
+                        "error_type": type(e).__name__,
+                        "error": str(e),
+                    }
+                    self.event.emit(
+                        AgentEvent(type=EventType.ERROR, data=llm_error_data)
+                    )
+                    llm_errors.append(llm_error_data)
+
                     if attempt < self.state.max_consecutive_failures - 1:
                         wait_time = 2 ** (attempt + 1)
                         logger.error(
@@ -229,7 +266,15 @@ def loop(self) -> AgentResult:
             if message is None:
                 error = f"Agent failed after exhausting retries: {last_error}"
                 self.event.emit(
-                    AgentEvent(type=EventType.ERROR, data={"step": step, "error": error})
+                    AgentEvent(
+                        type=EventType.ERROR,
+                        data={
+                            "step": step,
+                            "error": error,
+                            "llm_errors": llm_errors,
+                            "error_source": "llm_exhausted_retries",
+                        }
+                    )
                 )
                 return AgentResult(is_done=False, error=error)
 
@@ -369,6 +414,12 @@ async def aloop(self) -> AgentResult:
         for step in range(self.state.max_steps):
             self.state.step = step
 
+            if self.context.need_compaction:
+                messages=self.state.messages+self.state.error_messages
+                if content:=self.context.compact(messages):
+                    self.state.messages = [self.system_message, HumanMessage(content=content)]
+                self.state.error_messages.clear()
+
             # Check for loops and build state message with nudge
             nudge = None if self.disable_loop_detection else self._loop_guard.check()
             state_msg = self.context.state(
@@ -394,6 +445,7 @@ async def aloop(self) -> AgentResult:
                 try:
                     messages = list(chain(self.state.messages, self.state.error_messages))
                     llm_event = await self.llm.ainvoke(messages=messages, tools=self.tools)
+                    self.context.update_token_usage(llm_event.usage)
                     match llm_event.type:
                         case LLMEventType.TOOL_CALL:
                             message = ToolMessage(

windows_use/providers/events.py

@@ -12,10 +12,12 @@ class LLMStreamEventType(str, Enum):
     THINK_START = "think_start"
     THINK_DELTA = "think_delta"
     THINK_END = "think_end"
+    ERROR = "error"
 
 class LLMEventType(str, Enum):
     TEXT = "text"
     TOOL_CALL = "tool_call"
+    ERROR = "error"
 
 class Thinking(BaseModel):
     """Thinking/reasoning content with optional cryptographic signature (Anthropic)."""
@@ -41,4 +43,4 @@ class LLMEvent(BaseModel):
     thinking: Thinking | None = None
     content: str | None = None
     tool_call: ToolCall | None = None
-    usage: TokenUsage | None = None
+    usage: TokenUsage

windows_use/providers/views.py

@@ -4,13 +4,13 @@
 class TokenUsage(BaseModel):
     """Token usage information from LLM responses."""
 
-    prompt_tokens: int
-    completion_tokens: int
-    total_tokens: int
-    image_tokens: int | None = None
-    thinking_tokens: int | None = None
-    cache_creation_input_tokens: int | None = None
-    cache_read_input_tokens: int | None = None
+    prompt_tokens: int=0
+    completion_tokens: int=0
+    total_tokens: int=0
+    image_tokens: int=0
+    thinking_tokens: int=0
+    cache_creation_input_tokens: int=0
+    cache_read_input_tokens: int=0
 
 
 class Metadata(BaseModel):