context-optimization

Apply observation masking first to replace verbose tool outputs with compact references, then trigger compaction when utilization exceeds 70-80%. The ContextBudget class detects these thresholds and returns optimization reasons each agent loop iteration.

Observation masking replaces verbose tool outputs with short references like "[Obs:id elided. Key: summary]" once their purpose is served. The ObservationStore class keeps full content retrievable by reference ID, achieving 60-80% reduction with minimal quality impact.

Place stable content (system prompt, tool definitions, templates) at the prefix and dynamic content at the end. Remove timestamps and session IDs from system prompts, since even a single whitespace change invalidates the cached prefix downstream.

Compact when utilization crosses 70-80% and the task still fits one window. Partition only when estimated context exceeds 60% of the limit and at least 3 independent subtasks exist, since coordinator overhead can exceed savings on smaller tasks.

Compaction quality degrades when the summarizing model is itself under context pressure above 85% utilization. Trigger compaction at 70-80%, never compress the system prompt, and re-validate summaries against the current task goal afterward.

The built-in estimate uses a rough 4-characters-per-token heuristic for quick budget checks. Production systems should replace it with model-specific tokenizers such as tiktoken for OpenAI models or HuggingFace tokenizers for local models.