Context Compaction

The agent stores a provider-specific history list for each run. That history can contain screenshots from observations and tool results.

To avoid sending every screenshot on every model call, UIAgent.prepare_history_for_reasoning(...) delegates history reduction to:

model.prepare_history(
    history,
    max_observation_images=max_observation_images,
)

Why The Model Owns Compaction

History items are provider-specific:

• Gemini uses Content and Part objects.
• OpenAI-compatible models commonly use dictionaries with content arrays.
• Local models might use custom objects, file paths, base64 images, or separate image lists.

The core agent should not know those formats. Each model is responsible for compacting its own history representation.

Default Policy

The built-in Gemini model keeps image payloads in the latest max_observation_images image-bearing history items and removes image blobs from older image-bearing items.

Older text and function metadata can remain, so the model keeps continuity without carrying every screenshot.

Queue-Like Policy

A provider can implement compaction with queue semantics internally:

from collections import deque


def prepare_history(history, max_observation_images):
    keep = deque(maxlen=max_observation_images)

    for index, item in enumerate(history):
        if has_image(item):
            keep.append(index)

    keep_indexes = set(keep)
    ...

This gives the clarity of a bounded queue without adding a second stateful structure that can drift from the real history.

When To Return History Unchanged

Return history unchanged when:

• the model is text-only
• screenshots are stored outside of history
• the provider handles context truncation itself
• the implementation is experimental and correctness matters more than compactness